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. For instance, if calling the
20 recv/3 function with Timeout set to nowait (recv(Sock, 0, nowait)) when
21 there is actually nothing to read, it will return with {select, Se‐
22 lectInfo} (SelectInfo contains the SelectHandle). When data eventually
23 arrives a 'select' message will be sent to the caller:
24 : {'$socket', socket(), select, SelectHandle}
26 The caller can now call the recv function again and probably expect
28 data (it is really up to the OS network protocol implementation).
29 Note that all other users are locked out until the 'current user' has
31 called the function (recv in this case) and its return value shows that
32 the operation has completed. An operation can also be cancelled with
33 cancel/2.
34 Instead of Timeout = nowait it is equivalent to create a SelectHandle)
36 with make_ref() and give as Timeout. This will then be the SelectHandle
37 in the 'select' message, which enables a compiler optimization for re‐
38 ceiving a message containing a newly created reference() (ignore the
39 part of the message queue that had arrived before the the reference()
40 was created).
41 Another message the user must be prepared for (when making asynchronous
43 calls) is the abort message:
44 : {'$socket', socket(), abort, Info}
46 This message indicates that the (asynchronous) operation has been
48 aborted. If, for instance, the socket has been closed (by another
49 process), Info will be {SelectHandle, closed}.
50 Note:
53 There is currently no support for Windows.
54 Support for IPv6 has been implemented but not tested.
56 SCTP has only been partly implemented (and not tested).
58
61 invalid() = {invalid, What :: term()}
62 domain() = inet | inet6 | local | unspec
64 A lowercase atom() representing a protocol domain on the plat‐
66 form named AF_* (or PF_*).
67 The calls supports(), is_supported(ipv6) and is_supported(local)
69 tells if the IPv6 protocol for the inet6 protocol domain / ad‐
70 dress family, and if the local protocol domain / address family
71 is supported by the platform's header files.
72 type() = stream | dgram | raw | rdm | seqpacket
74 A lowercase atom() representing a protocol type on the platform
76 named SOCK_*.
77 protocol() = atom()
79 An atom() means any protocol as enumerated by the C library call
81 getprotoent() on the platform, or at least the supported ones of
82 ip | ipv6 | tcp | udp | sctp.
83 See open/2,3,4
85 The call supports(protocols) returns which protocols are sup‐
87 ported, and is_supported(protocols, Protocol) tells if Protocol
88 is among the enumerated.
89 socket() = {'$socket', socket_handle()}
91 As returned by open/1,2,3,4 and accept/1,2.
93 socket_handle()
95 An opaque socket handle unique for the socket.
97 select_tag()
99 A tag that describes the (select) operation, contained in the
101 returned select_info().
102 select_handle() = reference()
104 A reference() that uniquely identifies the (select) operation,
106 contained in the returned select_info().
107 select_info() =
109 {select_info,
110 SelectTag :: select_tag(),
111 SelectHandle :: select_handle()}
112 Returned by an operation that requires the caller to wait for a
114 select message containing the SelectHandle.
115 info() =
117 #{counters := #{atom() := integer() >= 0},
118 iov_max := integer() >= 0,
119 use_registry := boolean()}
120 The smallest allowed iov_max value according to POSIX is 16, but
122 check your platform documentation to be sure.
123 socket_counters() =
125 #{read_byte := integer() >= 0,
126 read_fails := integer() >= 0,
127 read_pkg := integer() >= 0,
128 read_pkg_max := integer() >= 0,
129 read_tries := integer() >= 0,
130 read_waits := integer() >= 0,
131 write_byte := integer() >= 0,
132 write_fails := integer() >= 0,
133 write_pkg := integer() >= 0,
134 write_pkg_max := integer() >= 0,
135 write_tries := integer() >= 0,
136 write_waits := integer() >= 0,
137 sendfile => integer() >= 0,
138 sendfile_byte => integer() >= 0,
139 sendfile_fails => integer() >= 0,
140 sendfile_max => integer() >= 0,
141 sendfile_pkg => integer() >= 0,
142 sendfile_pkg_max => integer() >= 0,
143 sendfile_tries => integer() >= 0,
144 sendfile_waits => integer() >= 0,
145 acc_success := integer() >= 0,
146 acc_fails := integer() >= 0,
147 acc_tries := integer() >= 0,
148 acc_waits := integer() >= 0}
149 info_keys() =
151 [domain | type | protocol | fd | owner | local_address |
152 remote_address | recv | sent | state]
153 Defines the information elements of the table(s) printed by the
155 i/0, i/1 and i/2 functions.
156 socket_info() =
158 #{domain := domain() | integer(),
159 type := type() | integer(),
160 protocol := protocol() | integer(),
161 owner := pid(),
162 ctype := normal | fromfd | {fromfd, integer()},
163 counters := socket_counters(),
164 num_readers := integer() >= 0,
165 num_writers := integer() >= 0,
166 num_acceptors := integer() >= 0,
167 writable := boolean(),
168 readable := boolean(),
169 rstates := [atom()],
170 wstates := [atom()]}
171 in_addr() = {0..255, 0..255, 0..255, 0..255}
173 in6_addr() =
175 {0..65535,
176 0..65535,
177 0..65535,
178 0..65535,
179 0..65535,
180 0..65535,
181 0..65535,
182 0..65535}
183 sockaddr() =
185 sockaddr_in() |
186 sockaddr_in6() |
187 sockaddr_un() |
188 sockaddr_ll() |
189 sockaddr_unspec() |
190 sockaddr_native()
191 sockaddr_recv() = sockaddr() | binary()
193 sockaddr_in() =
195 #{family := inet,
196 port := port_number(),
197 addr := any | broadcast | loopback | in_addr()}
198 sockaddr_in6() =
200 #{family := inet6,
201 port := port_number(),
202 addr := any | loopback | in6_addr(),
203 flowinfo := in6_flow_info(),
204 scope_id := in6_scope_id()}
205 sockaddr_un() = #{family := local, path := binary() | string()}
207 The path element will always be a binary when returned from this
209 module. When supplied to an API function in this module it may
210 be a string(), which will be encoded into a binary according to
211 the native file name encoding on the platform.
212 A terminating zero character will be appended before the address
214 path is given to the OS, and the terminating zero will be
215 stripped before giving the address path to the caller.
216 Linux's non-portable abstract socket address extension is han‐
218 dled by not doing any terminating zero processing in either di‐
219 rection, if the first byte of the address is zero.
220 sockaddr_ll() =
222 #{family := packet,
223 protocol := integer() >= 0,
224 ifindex := integer(),
225 pkttype := packet_type(),
226 hatype := integer() >= 0,
227 addr := binary()}
228 sockaddr_unspec() = #{family := unspec, addr := binary()}
230 sockaddr_native() = #{family := integer(), addr := binary()}
232 packet_type() =
234 host | broadcast | multicast | otherhost | outgoing |
235 loopback | user | kernel | fastroute |
236 integer() >= 0
237 port_number() = 0..65535
239 in6_flow_info() = 0..1048575
241 in6_scope_id() = 0..4294967295
243 msg_flag() =
245 cmsg_cloexec | confirm | ctrunc | dontroute | eor | errqueue |
246 more | oob | peek | trunc
247 Flags corresponding to the message flag constants on the plat‐
249 form. The flags are lowercase and the constants are uppercase
250 with the prefix MSG_.
251 Some flags are only used for sending, some only for receiving,
253 some in received control messages, and some for several of
254 these. Not all flags are supported on all platforms. See the
255 platform's documentation, supports(msg_flags), and is_sup‐
256 ported(msg_flags, MsgFlag).
257 level() = socket | protocol()
259 The OS protocol levels for, for example, socket options and con‐
261 trol messages, with the following names in the OS header files:
262 socket:
264 SOL_SOCKET with options named SO_*.
265 ip:
267 IPPROTO_IP a.k.a SOL_IP with options named IP_*.
268 ipv6:
270 IPPROTO_IPV6 a.k.a SOL_IPV6 with options named IPV6_*.
271 tcp:
273 IPPROTO_TCP with options named TCP_*.
274 udp:
276 IPPROTO_UDP with options named UDP_*.
277 sctp:
279 IPPROTO_SCTP with options named SCTP_*.
280 There are many other possible protocols, but the ones above are
282 those for which this socket library implements socket options
283 and/or control messages.
284 All protocols known to the OS are enumerated when the Erlang VM
286 is started. See the OS man page for protocols(5). The protocol
287 level 'socket' is always implemented as SOL_SOCKET and all the
288 others mentioned in the list above are valid, if supported by
289 the platform, enumerated or not.
290 The calls supports() and is_supported(protocols, Protocol) can
292 be used to find out if protocols ipv6 and/or sctp are supported
293 according to the platform's header files.
294 otp_socket_option() =
296 debug | iow | controlling_process | rcvbuf | rcvctrlbuf |
297 sndctrlbuf | meta | use_registry | fd | domain
298 These are socket options for the otp protocol level, that is
300 {otp, Name} options, above all OS protocol levels. They affect
301 Erlang/OTP's socket implementation.
302 debug:
304 boolean() - Activate debug printout.
305 iow:
307 boolean() - Inform On Wrap of statistics counters.
308 controlling_process:
310 pid() - The socket "owner". Only the current controlling
311 process can set this option.
312 rcvbuf:
314 BufSize :: (default | integer()>0) | {N :: integer()>0,
315 BufSize :: (default | integer()>0)} - Receive buffer size.
316 The value default is only valid to set. N specifies the num‐
317 ber of read attempts to do in a tight loop before assuming
318 no more data is pending.
319 rcvctrlbuf:
321 BufSize :: (default | integer()>0) - Buffer size for re‐
322 ceived ancillary messages. The value default is only valid
323 to set.
324 sndctrlbuf:
326 BufSize :: (default | integer()>0) - Buffer size for sent
327 ancillary messages. The value default is only valid to set.
328 fd:
330 integer() - Only valid to get. The OS protocol levels'
331 socket descriptor. Functions open/1,2 can be used to create
332 a socket according to this module from an existing OS socket
333 descriptor.
334 use_registry:
336 boolean() - Only valid to get. The value is set when the
337 socket is created with open/2 or open/4.
338 Options not described here are intentionally undocumented and
340 for Erlang/OTP internal use only.
341 socket_option() =
343 {Level :: socket,
344 Opt ::
345 acceptconn | acceptfilter | bindtodevice | broadcast |
346 busy_poll | debug | domain | dontroute | error |
347 keepalive | linger | mark | oobinline | passcred |
348 peek_off | peercred | priority | protocol | rcvbuf |
349 rcvbufforce | rcvlowat | rcvtimeo | reuseaddr |
350 reuseport | rxq_ovfl | setfib | sndbuf | sndbufforce |
351 sndlowat | sndtimeo | timestamp | type} |
352 {Level :: ip,
353 Opt ::
354 add_membership | add_source_membership | block_source |
355 dontfrag | drop_membership | drop_source_membership |
356 freebind | hdrincl | minttl | msfilter | mtu |
357 mtu_discover | multicast_all | multicast_if |
358 multicast_loop | multicast_ttl | nodefrag | options |
359 pktinfo | recvdstaddr | recverr | recvif | recvopts |
360 recvorigdstaddr | recvtos | recvttl | retopts |
361 router_alert | sndsrcaddr | tos | transparent | ttl |
362 unblock_source} |
363 {Level :: ipv6,
364 Opt ::
365 addrform | add_membership | authhdr | auth_level |
366 checksum | drop_membership | dstopts | esp_trans_level |
367 esp_network_level | faith | flowinfo | hopopts |
368 ipcomp_level | join_group | leave_group | mtu |
369 mtu_discover | multicast_hops | multicast_if |
370 multicast_loop | portrange | pktoptions | recverr |
371 recvhoplimit | hoplimit | recvpktinfo | pktinfo |
372 recvtclass | router_alert | rthdr | tclass |
373 unicast_hops | use_min_mtu | v6only} |
374 {Level :: tcp,
375 Opt ::
376 congestion | cork | info | keepcnt | keepidle |
377 keepintvl | maxseg | md5sig | nodelay | noopt | nopush |
378 syncnt | user_timeout} |
379 {Level :: udp, Opt :: cork} |
380 {Level :: sctp,
381 Opt ::
382 adaption_layer | associnfo | auth_active_key |
383 auth_asconf | auth_chunk | auth_key | auth_delete_key |
384 autoclose | context | default_send_params |
385 delayed_ack_time | disable_fragments | hmac_ident |
386 events | explicit_eor | fragment_interleave |
387 get_peer_addr_info | initmsg | i_want_mapped_v4_addr |
388 local_auth_chunks | maxseg | maxburst | nodelay |
389 partial_delivery_point | peer_addr_params |
390 peer_auth_chunks | primary_addr | reset_streams |
391 rtoinfo | set_peer_primary_addr | status |
392 use_ext_recvinfo}
393 Socket option on the form {Level, Opt} where the OS protocol
395 Level = level() and Opt is a socket option on that protocol
396 level.
397 The OS name for an options is, except where otherwise noted, the
399 Opt atom, in capitals, with prefix according to level().
400 Note:
402 The IPv6 option pktoptions is a special (barf) case. It is in‐
403 tended for backward compatibility usage only.
404 Do not use this option.
406 Note:
409 See the OS documentation for every socket option.
410 An option below that has the value type boolean() will translate
413 the value false to a C int with value 0, and the value true to
414 !!0 (not (not false)).
415 An option with value type integer() will be translated to a C
417 int that may have a restricted range, for example byte: 0..255.
418 See the OS documentation.
419 The calls supports(options), supports(options, Level) and
421 is_supported(options, {Level, Opt}) can be used to find out
422 which socket options that are supported by the platform.
423 Options for protocol level socket:
425 {socket, acceptconn}:
427 Value = boolean()
428 {socket, bindtodevice}:
430 Value = string()
431 {socket, broadcast}:
433 Value = boolean()
434 {socket, debug}:
436 Value = integer()
437 {socket, domain}:
439 Value = domain()
440 Only valid to get.
442 The socket's protocol domain. Does not work on for instance
444 FreeBSD.
445 {socket, dontroute}:
447 Value = boolean()
448 {socket, keepalive}:
450 Value = boolean()
451 {socket, linger}:
453 Value = abort | linger()
454 The value abort is shorthand for #{onoff => true, linger =>
456 0}, and only valid to set.
457 {socket, oobinline}:
459 Value = boolean()
460 {socket, passcred}:
462 Value = boolean()
463 {socket, peek_off}:
465 Value = integer()
466 Currently disabled due to a possible infinite loop when
468 calling recv/1-4 with peek in Flags.
469 {socket, priority}:
471 Value = integer()
472 {socket, protocol}:
474 Value = protocol()
475 Only valid to get.
477 The socket's protocol. Does not work on for instance Darwin.
479 {socket, rcvbuf}:
481 Value = integer()
482 {socket, rcvlowat}:
484 Value = integer()
485 {socket, rcvtimeo}:
487 Value = timeval()
488 This option is unsupported per default; OTP has to be ex‐
490 plicitly built with the --enable-esock-rcvsndtimeo configure
491 option for this to be available.
492 Since our implementation uses nonblocking sockets, it is un‐
494 known if and how this option works, or even if it may cause
495 malfunction. Therefore, we do not recommend setting this op‐
496 tion.
497 Instead, use the Timeout argument to, for instance, the
499 recv/3 function.
500 {socket, reuseaddr}:
502 Value = boolean()
503 {socket, reuseport}:
505 Value = boolean()
506 {socket, sndbuf}:
508 Value = integer()
509 {socket, sndlowat}:
511 Value = integer()
512 {socket, sndtimeo}:
514 Value = timeval()
515 This option is unsupported per default; OTP has to be ex‐
517 plicitly built with the --enable-esock-rcvsndtimeo configure
518 option for this to be available.
519 Since our implementation uses nonblocking sockets, it is un‐
521 known if and how this option works, or even if it may cause
522 malfunction. Therefore, we do not recommend setting this op‐
523 tion.
524 Instead, use the Timeout argument to, for instance, the
526 send/3 function.
527 {socket, timestamp}:
529 Value = boolean()
530 {socket, type}:
532 Value = type()
533 Only valid to get.
535 The socket's type.
537 Options for protocol level ip:
539 {ip, add_membership}:
541 Value = ip_mreq()
542 Only valid to set.
544 {ip, add_source_membership}:
546 Value = ip_mreq_source()
547 Only valid to set.
549 {ip, block_source}:
551 Value = ip_mreq_source()
552 Only valid to set.
554 {ip, drop_membership}:
556 Value = ip_mreq()
557 Only valid to set.
559 {ip, drop_source_membership}:
561 Value = ip_mreq_source()
562 Only valid to set.
564 {ip, freebind}:
566 Value = boolean()
567 {ip, hdrincl}:
569 Value = boolean()
570 {ip, minttl}:
572 Value = integer()
573 {ip, msfilter}:
575 Value = null | ip_msfilter()
576 Only valid to set.
578 The value null passes a NULL pointer and size 0 to the C li‐
580 brary call.
581 {ip, mtu}:
583 Value = integer()
584 Only valid to get.
586 {ip, mtu_discover}:
588 Value = ip_pmtudisc() | integer()
589 An integer() value is according to the platform's header
591 files.
592 {ip, multicast_all}:
594 Value = boolean()
595 {ip, multicast_if}:
597 Value = any | in_addr()
598 {ip, multicast_loop}:
600 Value = boolean()
601 {ip, multicast_ttl}:
603 Value = integer()
604 {ip, nodefrag}:
606 Value = boolean()
607 {ip, pktinfo}:
609 Value = boolean()
610 {ip, recvdstaddr}:
612 Value = boolean()
613 {ip, recverr}:
615 Value = boolean()
616 Warning! When this option is enabled, error messages may ar‐
618 rive on the socket's error queue, which should be read using
619 the message flag errqueue, and using recvmsg/1,2,3,4,5 to
620 get all error information in the message's ctrl field as a
621 control message #{level := ip, type := recverr}.
622 A working strategy should be to first poll the error queue
624 using recvmsg/2,3,4 with Timeout =:= 0 and Flags containing
625 errqueue (ignore the return value {error, timeout}) before
626 reading the actual data to ensure that the error queue gets
627 cleared. And read the data using one of the nowait | se‐
628 lect_handle() recv functions: recv/3,4, recvfrom/3,4 or
629 recvmsg/3,4,5. Otherwise you might accidentally cause a busy
630 loop in and out of 'select' for the socket.
631 {ip, recvif}:
633 Value = boolean()
634 {ip, recvopts}:
636 Value = boolean()
637 {ip, recvorigdstaddr}:
639 Value = boolean()
640 {ip, recvtos}:
642 Value = boolean()
643 {ip, recvttl}:
645 Value = boolean()
646 {ip, retopts}:
648 Value = boolean()
649 {ip, router_alert}:
651 Value = integer()
652 {ip, sendsrcaddr}:
654 Value = boolean()
655 {ip, tos}:
657 Value = ip_tos() | integer()
658 An integer() value is according to the platform's header
660 files.
661 {ip, transparent}:
663 Value = boolean()
664 {ip, ttl}:
666 Value = integer()
667 {ip, unblock_source}:
669 Value = ip_mreq_source()
670 Only valid to set.
672 Options for protocol level ipv6:
674 {ipv6, addrform}:
676 Value = domain()
677 As far as we know the only valid value is inet and it is
679 only allowed for an IPv6 socket that is connected and bound
680 to an IPv4-mapped IPv6 address.
681 {ipv6, add_membership}:
683 Value = ipv6_mreq()
684 Only valid to set.
686 {ipv6, authhdr}:
688 Value = boolean()
689 {ipv6, drop_membership}:
691 Value = ipv6_mreq()
692 Only valid to set.
694 {ipv6, dstopts}:
696 Value = boolean()
697 {ipv6, flowinfo}:
699 Value = boolean()
700 {ipv6, hoplimit}:
702 Value = boolean()
703 {ipv6, hopopts}:
705 Value = boolean()
706 {ipv6, mtu}:
708 Value = integer()
709 {ipv6, mtu_discover}:
711 Value = ipv6_pmtudisc() | integer()
712 An integer() value is according to the platform's header
714 files.
715 {ipv6, multicast_hops}:
717 Value = ipv6_hops()
718 {ipv6, multicast_if}:
720 Value = integer()
721 {ipv6, multicast_loop}:
723 Value = boolean()
724 {ipv6, recverr}:
726 Value = boolean()
727 Warning! See the socket option {ip, recverr} regarding the
729 socket's error queue. The same warning applies for this op‐
730 tion.
731 {ipv6, recvhoplimit}:
733 Value = boolean()
734 {ipv6, recvpktinfo}:
736 Value = boolean()
737 {ipv6, recvtclass}:
739 Value = boolean()
740 {ipv6, router_alert}:
742 Value = integer()
743 {ipv6, rthdr}:
745 Value = boolean()
746 {ipv6, tclass}:
748 Value = boolean()
749 {ipv6, unicast_hops}:
751 Value = ipv6_hops()
752 {ipv6, v6only}:
754 Value = boolean()
755 Options for protocol level sctp. See also RFC 6458.
757 {sctp, associnfo}:
759 Value = sctp_assocparams()
760 {sctp, autoclose}:
762 Value = integer()
763 {sctp, disable_fragments}:
765 Value = boolean()
766 {sctp, events}:
768 Value = sctp_event_subscribe()
769 Only valid to set.
771 {sctp, initmsg}:
773 Value = sctp_initmsg()
774 {sctp, maxseg}:
776 Value = integer()
777 {sctp, nodelay}:
779 Value = boolean()
780 {sctp, rtoinfo}:
782 Value = sctp_rtoinfo()
783 Options for protocol level tcp:
785 {tcp, congestion}:
787 Value = string()
788 {tcp, cork}:
790 Value = boolean()
791 {tcp, maxseg}:
793 Value = integer()
794 {tcp, nodelay}:
796 Value = boolean()
797 Options for protocol level udp:
799 {udp, cork}:
801 Value = boolean()
802 linger() = #{onoff := boolean(), linger := integer() >= 0}
804 Corresponds to the C struct linger for managing the socket op‐
806 tion {socket, linger}.
807 timeval() = #{sec := integer(), usec := integer()}
809 Corresponds to the C struct timeval. The field sec holds sec‐
811 onds, and usec microseconds.
812 ip_mreq() = #{multiaddr := in_addr(), interface := in_addr()}
814 Corresponds to the C struct ip_mreq for managing multicast
816 groups.
817 ip_mreq_source() =
819 #{multiaddr := in_addr(),
820 interface := in_addr(),
821 sourceaddr := in_addr()}
822 Corresponds to the C struct ip_mreq_source for managing multi‐
824 cast groups.
825 ip_msfilter() =
827 #{multiaddr := in_addr(),
828 interface := in_addr(),
829 mode := include | exclude,
830 slist := [in_addr()]}
831 Corresponds to the C struct ip_msfilter for managing multicast
833 source filtering (RFC 3376).
834 ip_pmtudisc() = want | dont | do | probe
836 Lowercase atom() values corresponding to the C library constants
838 IP_PMTUDISC_*. Some constant(s) may be unsupported by the plat‐
839 form.
840 ip_tos() = lowdelay | throughput | reliability | mincost
842 Lowercase atom() values corresponding to the C library constants
844 IPTOS_*. Some constant(s) may be unsupported by the platform.
845 ip_pktinfo() =
847 #{ifindex := integer() >= 0,
848 spec_dst := in_addr(),
849 addr := in_addr()}
850 ipv6_mreq() =
852 #{multiaddr := in6_addr(), interface := integer() >= 0}
853 Corresponds to the C struct ipv6_mreq for managing multicast
855 groups. See also RFC 2553.
856 ipv6_hops() = default | 0..255
858 The value default is only valid to set and is translated to the
860 C value -1, meaning the route default.
861 ipv6_pmtudisc() = want | dont | do | probe
863 Lowercase atom() values corresponding to the C library constants
865 IPV6_PMTUDISC_*. Some constant(s) may be unsupported by the
866 platform.
867 ipv6_pktinfo() = #{addr := in6_addr(), ifindex := integer()}
869 sctp_assocparams() =
871 #{assoc_id := integer(),
872 asocmaxrxt := 0..65535,
873 numbe_peer_destinations := 0..65535,
874 peer_rwnd := 0..4294967295,
875 local_rwnd := 0..4294967295,
876 cookie_life := 0..4294967295}
877 Corresponds to the C struct sctp_assocparams.
879 sctp_event_subscribe() =
881 #{data_io := boolean(),
882 association := boolean(),
883 address := boolean(),
884 send_failure := boolean(),
885 peer_error := boolean(),
886 shutdown := boolean(),
887 partial_delivery := boolean(),
888 adaptation_layer => boolean(),
889 sender_dry => boolean()}
890 Corresponds to the C struct sctp_event_subscribe.
892 Not all fields are implemented on all platforms; unimplemented
894 fields are ignored, but implemented fields are mandatory. Note
895 that the '_event' suffixes have been stripped from the C struct
896 field names, for convenience.
897 sctp_initmsg() =
899 #{num_ostreams := 0..65535,
900 max_instreams := 0..65535,
901 max_attempts := 0..65535,
902 max_init_timeo := 0..65535}
903 Corresponds to the C struct sctp_initmsg.
905 sctp_rtoinfo() =
907 #{assoc_id := integer(),
908 initial := 0..4294967295,
909 max := 0..4294967295,
910 min := 0..4294967295}
911 Corresponds to the C struct sctp_rtoinfo.
913 msg() = msg_send() | msg_recv()
915 msg_send() =
917 #{addr => sockaddr(),
918 iov := erlang:iovec(),
919 ctrl =>
920 [cmsg_send() |
921 #{level := level() | integer(),
922 type := integer(),
923 data := binary()}]}
924 Message sent by sendmsg/2,3,4.
926 Corresponds to a C struct msghdr, see your platform documenta‐
928 tion for sendmsg(2).
929 addr:
931 Optional peer address, used on unconnected sockets. Corre‐
932 sponds to msg_name and msg_namelen fields of a struct ms‐
933 ghdr. If not used they are set to NULL, 0.
934 iov:
936 Mandatory data as a list of binaries. The msg_iov and
937 msg_iovlen fields of a struct msghdr.
938 ctrl:
940 Optional list of control messages (CMSG). Corresponds to
941 the msg_control and msg_controllen fields of a struct ms‐
942 ghdr. If not used they are set to NULL, 0.
943 The msg_flags field of the struct msghdr is set to 0.
945 msg_recv() =
947 #{addr => sockaddr_recv(),
948 iov := erlang:iovec(),
949 ctrl :=
950 [cmsg_recv() |
951 #{level := level() | integer(),
952 type := integer(),
953 data := binary()}],
954 flags := [msg_flag() | integer()]}
955 Message returned by recvmsg/1,2,3,5.
957 Corresponds to a C struct msghdr, see your platform documenta‐
959 tion for recvmsg(2).
960 addr:
962 Optional peer address, used on unconnected sockets. Corre‐
963 sponds to msg_name and msg_namelen fields of a struct ms‐
964 ghdr. If NULL the map key is not present.
965 iov:
967 Data as a list of binaries. The msg_iov and msg_iovlen
968 fields of a struct msghdr.
969 ctrl:
971 A possibly empty list of control messages (CMSG). Corre‐
972 sponds to the msg_control and msg_controllen fields of a
973 struct msghdr.
974 flags:
976 Message flags. Corresponds to the msg_flags field of a
977 struct msghdr. Unknown flags, if any, are returned in one
978 integer(), last in the containing list.
979 native_value() = integer() | boolean() | binary()
981 cmsg_send() =
983 #{level := socket,
984 type := timestamp,
985 data => native_value(),
986 value => timeval()} |
987 #{level := socket, type := rights, data := native_value()} |
988 #{level := socket,
989 type := credentials,
990 data := native_value()} |
991 #{level := ip,
992 type := tos,
993 data => native_value(),
994 value => ip_tos() | integer()} |
995 #{level := ip,
996 type := ttl,
997 data => native_value(),
998 value => integer()} |
999 #{level := ip,
1000 type := hoplimit,
1001 data => native_value(),
1002 value => integer()} |
1003 #{level := ipv6,
1004 type := tclass,
1005 data => native_value(),
1006 value => integer()}
1007 Control messages (ancillary messages) accepted by sendmsg/2,3,4.
1009 A control message may for some message types have a value field
1011 with a symbolic value, or a data field with a native value, that
1012 has to be binary compatible what is defined in the platform's
1013 header files.
1014 cmsg_recv() =
1016 #{level := socket,
1017 type := timestamp,
1018 data := binary(),
1019 value => timeval()} |
1020 #{level := socket, type := rights, data := binary()} |
1021 #{level := socket, type := credentials, data := binary()} |
1022 #{level := ip,
1023 type := tos,
1024 data := binary(),
1025 value => ip_tos() | integer()} |
1026 #{level := ip,
1027 type := recvtos,
1028 data := binary(),
1029 value := ip_tos() | integer()} |
1030 #{level := ip,
1031 type := ttl,
1032 data := binary(),
1033 value => integer()} |
1034 #{level := ip,
1035 type := recvttl,
1036 data := binary(),
1037 value := integer()} |
1038 #{level := ip,
1039 type := pktinfo,
1040 data := binary(),
1041 value => ip_pktinfo()} |
1042 #{level := ip,
1043 type := origdstaddr,
1044 data := binary(),
1045 value => sockaddr_recv()} |
1046 #{level := ip,
1047 type := recverr,
1048 data := binary(),
1049 value => extended_err()} |
1050 #{level := ipv6,
1051 type := hoplimit,
1052 data := binary(),
1053 value => integer()} |
1054 #{level := ipv6,
1055 type := pktinfo,
1056 data := binary(),
1057 value => ipv6_pktinfo()} |
1058 #{level := ipv6,
1059 type := recverr,
1060 data := binary(),
1061 value => extended_err()} |
1062 #{level := ipv6,
1063 type := tclass,
1064 data := binary(),
1065 value => integer()}
1066 Control messages (ancillary messages) returned by
1068 recvmsg/1,2,3,5.
1069 A control message has got a data field with a native (binary)
1071 value for the message data, and may also have a decoded value
1072 field if this socket library succesfully decoded the data.
1073 icmp_dest_unreach() =
1075 net_unreach | host_unreach | port_unreach | frag_needed |
1076 net_unknown | host_unknown
1077 icmpv6_dest_unreach() =
1079 noroute | adm_prohibited | not_neighbour | addr_unreach |
1080 port_unreach | policy_fail | reject_route
1081 ee_origin() = none | local | icmp | icmp6
1083 extended_err() =
1085 #{error := posix(),
1086 origin := icmp,
1087 type := dest_unreach,
1088 code := icmp_dest_unreach() | 0..255,
1089 info := 0..4294967295,
1090 data := 0..4294967295,
1091 offender := sockaddr_recv()} |
1092 #{error := posix(),
1093 origin := icmp,
1094 type := time_exceeded | 0..255,
1095 code := 0..255,
1096 info := 0..4294967295,
1097 data := 0..4294967295,
1098 offender := sockaddr_recv()} |
1099 #{error := posix(),
1100 origin := icmp6,
1101 type := dest_unreach,
1102 code := icmpv6_dest_unreach() | 0..255,
1103 info := 0..4294967295,
1104 data := 0..4294967295,
1105 offender := sockaddr_recv()} |
1106 #{error := posix(),
1107 origin := icmp6,
1108 type := pkt_toobig | time_exceeded | 0..255,
1109 code := 0..255,
1110 info := 0..4294967295,
1111 data := 0..4294967295,
1112 offender := sockaddr_recv()} |
1113 #{error := posix(),
1114 origin := ee_origin() | 0..255,
1115 type := 0..255,
1116 code := 0..255,
1117 info := 0..4294967295,
1118 data := 0..4294967295,
1119 offender := sockaddr_recv()}
1120 posix() = inet:posix()
1122 The POSIX error codes originates from the OS level socket inter‐
1124 face.
1125
1127 accept(ListenSocket) -> {ok, Socket} | {error, Reason}
1128 accept(ListenSocket, Timeout :: infinity) ->
1130 {ok, Socket} | {error, Reason}
1131 Types:
1133 ListenSocket = Socket = socket()
1135 Reason = posix() | closed | invalid()
1136 Accept a connection on a socket.
1138 This call is used with connection oriented socket types (stream
1140 or seqpacket). It returns the first pending incoming connection
1141 for a listen socket, or waits for one to arrive, and returns the
1142 (newly) connected socket.
1143 accept(ListenSocket, Timeout :: integer() >= 0) ->
1145 {ok, Socket} | {error, Reason}
1146 Types:
1148 ListenSocket = Socket = socket()
1150 Reason = posix() | closed | invalid() | timeout
1151 The same as accept/1 but returns {error, timeout} if no connec‐
1153 tion has been accepted after Timeout milliseconds.
1154 accept(ListenSocket, Timeout :: nowait) ->
1156 {ok, Socket} | {select, SelectInfo} | {error, Reason}
1157 accept(ListenSocket, SelectHandle :: select_handle()) ->
1159 {ok, Socket} | {select, SelectInfo} | {error, Reason}
1160 Types:
1162 ListenSocket = Socket = socket()
1164 SelectInfo = select_info()
1165 Reason = posix() | closed | invalid()
1166 The same as accept/1 but returns promptly.
1168 When there is no pending connection to return, the function will
1170 return {select, SelectInfo}, and the caller will later receive a
1171 select message, {'$socket', Socket, select, SelectHandle} ( with
1172 the SelectHandle contained in the SelectInfo ) when a client
1173 connects. A subsequent call to accept/1,2 will then return the
1174 socket.
1175 If the time-out argument is SelectHandle, that term will be con‐
1177 tained in a returned SelectInfo and the corresponding select
1178 message. The SelectHandle is presumed to be unique to this call.
1179 If the time-out argument is nowait, and a SelectInfo is re‐
1181 turned, it will contain a select_handle() generated by the call.
1182 If the caller doesn't want to wait for a connection, it must im‐
1184 mediately call cancel/2 to cancel the operation.
1185 bind(Socket, Addr) -> ok | {error, Reason}
1187 Types:
1189 Socket = socket()
1191 Addr = sockaddr() | any | broadcast | loopback
1192 Reason = posix() | closed | invalid()
1193 Bind a name to a socket.
1195 When a socket is created (with open), it has no address assigned
1197 to it. bind assigns the address specified by the Addr argument.
1198 The rules used for name binding vary between domains.
1200 If you bind a socket to an address in for example the 'inet' or
1202 'inet6' address families, with an ephemeral port number (0), and
1203 want to know which port that was chosen, you can find out using
1204 something like: {ok, #{port := Port}} = socket:sockname(Socket)
1205 cancel(Socket, SelectInfo) -> ok | {error, Reason}
1207 Types:
1209 Socket = socket()
1211 SelectInfo = select_info()
1212 Reason = closed | invalid()
1213 Cancel an asynchronous request.
1215 Call this function in order to cancel a previous asynchronous
1217 call to, e.g. recv/3.
1218 An ongoing asynchronous operation blocks the socket until the
1220 operation has been finished in good order, or until it has been
1221 cancelled by this function.
1222 Any other process that tries an operation of the same basic type
1224 (accept / send / recv) will be enqueued and notified with the
1225 regular select mechanism for asynchronous operations when the
1226 current operation and all enqueued before it has been completed.
1227 If SelectInfo does not match an operation in progress for the
1229 calling process, this function returns {error, {invalid, Select‐
1230 Info}}.
1231 close(Socket) -> ok | {error, Reason}
1233 Types:
1235 Socket = socket()
1237 Reason = posix() | closed | timeout
1238 Closes the socket.
1240 Note:
1242 Note that for e.g. protocol = tcp, most implementations doing a
1243 close does not guarantee that any data sent is delivered to the
1244 recipient before the close is detected at the remote side.
1245 One way to handle this is to use the shutdown function
1247 (socket:shutdown(Socket, write)) to signal that no more data is
1248 to be sent and then wait for the read side of the socket to be
1249 closed.
1250 connect(Socket, SockAddr) -> ok | {error, Reason}
1253 connect(Socket, SockAddr, Timeout :: infinity) ->
1255 ok | {error, Reason}
1256 Types:
1258 Socket = socket()
1260 SockAddr = sockaddr()
1261 Reason = posix() | closed | invalid() | already
1262 This function connects the socket to the address specified by
1264 the SockAddr argument, and returns when the connection has been
1265 established or failed.
1266 If a connection attempt is already in progress (by another
1268 process), {error, already} is returned.
1269 connect(Socket, SockAddr, Timeout :: integer() >= 0) ->
1271 ok | {error, Reason}
1272 Types:
1274 Socket = socket()
1276 SockAddr = sockaddr()
1277 Reason = posix() | closed | invalid() | already | timeout
1278 The same as connect/2 but returns {error, timeout} if no connec‐
1280 tion has been established after Timeout milliseconds.
1281 Note:
1283 Note that when this call has returned {error, timeout the con‐
1284 nection state of the socket is uncertain since the platform's
1285 network stack may complete the connection at any time, up to
1286 some platform specific time-out.
1287 Repeating a connection attempt towards the same address would be
1289 ok, but towards a different address could end up with a connec‐
1290 tion to either address.
1291 The safe play would be to close the socket and start over.
1293 Also note that all this applies to cancelling a connect call
1295 with a no-wait time-out described below.
1296 connect(Socket, SockAddr, Timeout :: nowait) ->
1299 ok | {select, SelectInfo} | {error, Reason}
1300 connect(Socket, SockAddr, SelectHandle :: select_handle()) ->
1302 ok | {select, SelectInfo} | {error, Reason}
1303 Types:
1305 Socket = socket()
1307 SockAddr = sockaddr()
1308 SelectInfo = select_info()
1309 Reason = posix() | closed | invalid() | already
1310 The same as connect/2 but returns promptly.
1312 If it is not possible to immediately establish a connection, the
1314 function will return {select, SelectInfo}, and the caller will
1315 later receive a select message, {'$socket', Socket, select, Se‐
1316 lectHandle} ( with the SelectHandle contained in the SelectInfo
1317 ) when the connection has been completed or failed. A subsequent
1318 call to connect/1 will then finalize the connection and return
1319 the result.
1320 If the time-out argument is SelectHandle, that term will be con‐
1322 tained in a returned SelectInfo and the corresponding select
1323 message. The SelectHandle is presumed to be unique to this call.
1324 If the time-out argument is nowait, and a SelectInfo is re‐
1326 turned, it will contain a select_handle() generated by the call.
1327 If the caller doesn't want to wait for the connection to com‐
1329 plete, it must immediately call cancel/2 to cancel the opera‐
1330 tion.
1331 connect(Socket) -> ok | {error, Reason}
1333 Types:
1335 Socket = socket()
1337 Reason = posix() | closed | invalid()
1338 This function finalizes a connection setup on a socket, after
1340 calling connect(_, _, nowait | select_handle()) that returned
1341 {select, SelectInfo}, and receiving the select message
1342 {'$socket', Socket, select, SelectHandle}, and returns whether
1343 the connection setup was succesful or not.
1344 Instead of calling this function, for backwards compatibility,
1346 it is allowed to call connect/2,3, but that incurs more overhead
1347 since the connect address and time-out are processed in vain.
1348 cancel_monitor(MRef) -> boolean()
1350 Types:
1352 MRef = reference()
1354 If MRef is a reference that the calling process obtained by
1356 calling monitor/1, this monitor is turned off. If the monitoring
1357 is already turned off, nothing happens.
1358 The returned value is one of the following:
1360 true:
1362 The monitor was found and removed. In this case, no 'DOWN'
1363 message corresponding to this monitor has been delivered and
1364 will not be delivered.
1365 false:
1367 The monitor was not found and could not be removed. This
1368 probably because a 'DOWN' message corresponding to this mon‐
1369 itor has already been placed in the caller message queue.
1370 Failure: It is an error if MRef refers to a monitor started by
1372 another process.
1373 getopt(X1 :: socket(),
1375 SocketOption :: {Level :: otp, Opt :: otp_socket_option()}) ->
1376 {ok, Value :: term()} | {error, invalid() | closed}
1377 Gets a socket option from the protocol level otp, which is this
1379 implementation's level above the OS protocol layers.
1380 See the type otp_socket_option() for a description of the op‐
1382 tions on this level.
1383 getopt(X1 :: socket(), SocketOption :: socket_option()) ->
1385 {ok, Value :: term()} |
1386 {error, posix() | invalid() | closed}
1387 Gets a socket option from one of the OS's protocol levels. See
1389 the type socket_option() for which options that this implementa‐
1390 tion knows about, how they are related to option names in the
1391 OS, and if there are known pecularities with any of them.
1392 What options are valid depends on what kind of socket it is (do‐
1394 main(), type() and protocol()).
1395 See the socket options chapter of the users guide for more
1397 info.
1398 Note:
1400 Not all options are valid, nor possible to get, on all plat‐
1401 forms. That is, even if "we" support an option; it does not mean
1402 that the underlying OS does.
1403 getopt(Socket, Level, Opt) -> ok | {error, Reason}
1406 Types:
1408 Socket = socket()
1410 Reason = inet:posix() | invalid() | closed
1411 Backwards compatibility function.
1413 The same as getopt(Socket, {Level, Opt})
1415 getopt_native(X1 :: socket(),
1417 SocketOption ::
1418 socket_option() |
1419 {Level :: level() | (NativeLevel :: integer()),
1420 NativeOpt :: integer()},
1421 ValueType :: integer) ->
1422 {ok, Value :: integer()} |
1423 {error, posix() | invalid() | closed}
1424 getopt_native(X1 :: socket(),
1426 SocketOption ::
1427 socket_option() |
1428 {Level :: level() | (NativeLevel :: integer()),
1429 NativeOpt :: integer()},
1430 ValueType :: boolean) ->
1431 {ok, Value :: boolean()} |
1432 {error, posix() | invalid() | closed}
1433 getopt_native(X1 :: socket(),
1435 SocketOption ::
1436 socket_option() |
1437 {Level :: level() | (NativeLevel :: integer()),
1438 NativeOpt :: integer()},
1439 ValueSize :: integer() >= 0) ->
1440 {ok, Value :: binary()} |
1441 {error, posix() | invalid() | closed}
1442 getopt_native(X1 :: socket(),
1444 SocketOption ::
1445 socket_option() |
1446 {Level :: level() | (NativeLevel :: integer()),
1447 NativeOpt :: integer()},
1448 ValueSpec :: binary()) ->
1449 {ok, Value :: binary()} |
1450 {error, posix() | invalid() | closed}
1451 Gets a socket option that may be unknown to our implementation,
1453 or that has a type not compatible with our implementation, that
1454 is; in "native mode".
1455 The socket option may be specified with an ordinary socket_op‐
1457 tion() tuple, with a known Level = level() and an integer Na‐
1458 tiveOpt, or with both an integer NativeLevel and NativeOpt.
1459 How to decode the option value has to be specified either with
1461 ValueType, by specifying the ValueSize for a binary() that will
1462 contain the fetched option value, or by specifying a binary()
1463 ValueSpec that will be copied to a buffer for the getsockopt()
1464 call to write the value in which will be returned as a new bi‐
1465 nary().
1466 If ValueType is integer a C type (int) will be fetched, if it is
1468 boolean a C type (int) will be fetched and converted into a
1469 boolean() according to the C implementation.
1470 What options are valid depends on what kind of socket it is (do‐
1472 main(), type() and protocol()).
1473 The integer values for NativeLevel and NativeOpt as well as the
1475 Value encoding has to be deduced from the header files for the
1476 running system.
1477 i() -> ok
1479 Print all sockets in table format in the erlang shell.
1481 i(InfoKeys) -> ok
1483 Types:
1485 InfoKeys = info_keys()
1487 Print all sockets in table format in the erlang shell. What in‐
1489 formation is included is defined by InfoKeys.
1490 i(Domain) -> ok
1492 Types:
1494 Domain = inet | inet6 | local
1496 Print a selection, based on domain, of the sockets in table for‐
1498 mat in the erlang shell.
1499 i(Proto) -> ok
1501 Types:
1503 Proto = sctp | tcp | udp
1505 Print a selection, based on protocol, of the sockets in table
1507 format in the erlang shell.
1508 i(Type) -> ok
1510 Types:
1512 Type = dgram | seqpacket | stream
1514 Print a selection, based on type, of the sockets in table format
1516 in the erlang shell.
1517 i(Domain, InfoKeys) -> ok
1519 Types:
1521 Domain = inet | inet6 | local
1523 InfoKeys = info_keys()
1524 Print a selection, based on domain, of the sockets in table for‐
1526 mat in the erlang shell. What information is included is defined
1527 by InfoKeys.
1528 i(Proto, InfoKeys) -> ok
1530 Types:
1532 Proto = sctp | tcp | udp
1534 InfoKeys = info_keys()
1535 Print a selection, based on domain, of the sockets in table for‐
1537 mat in the erlang shell. What information is included is defined
1538 by InfoKeys.
1539 i(Type, InfoKeys) -> ok
1541 Types:
1543 Type = dgram | seqpacket | stream
1545 InfoKeys = info_keys()
1546 Print a selection, based on type, of the sockets in table format
1548 in the erlang shell. What information is included is defined by
1549 InfoKeys.
1550 info() -> info()
1552 Get miscellaneous info about the socket library.
1554 The function returns a map with each info item as a key-value
1556 binding.
1557 Note:
1559 In order to ensure data integrity, mutex'es are taken when
1560 needed. So, do not call this function often.
1561 info(Socket) -> socket_info()
1564 Types:
1566 Socket = socket()
1568 Get miscellaneous info about the socket.
1570 The function returns a map with each info item as a key-value
1572 binding. It reflects the "current" state of the socket.
1573 Note:
1575 In order to ensure data integrity, mutex'es are taken when
1576 needed. So, do not call this function often.
1577 is_supported(Key1 :: term()) -> boolean()
1580 is_supported(Key1 :: term(), Key2 :: term()) -> boolean()
1582 This function retreives information about what the platform sup‐
1584 ports, such as if SCTP is supported, or if a socket options are
1585 supported.
1586 For keys other than the known false is returned. Note that in a
1588 future version or on a different platform there might be more
1589 supported items.
1590 This functions returns a boolean corresponding to what sup‐
1592 ports/0-2 reports for the same Key1 (and Key2).
1593 listen(Socket) -> ok | {error, Reason}
1595 listen(Socket, Backlog) -> ok | {error, Reason}
1597 Types:
1599 Socket = socket()
1601 Backlog = integer()
1602 Reason = posix() | closed
1603 Listen for connections on a socket.
1605 monitor(Socket) -> reference()
1607 Types:
1609 Socket = socket()
1611 Start monitor the socket Socket.
1613 If the monitored socket does not exist or when the monitor is
1615 triggered, a 'DOWN' message is sent that has the following pat‐
1616 tern:
1617 {'DOWN', MonitorRef, socket, Object, Info}
1619 In the monitor message MonitorRef and Type are the same as de‐
1622 scribed earlier, and:
1623 Object:
1625 The monitored entity, socket, which triggered the event.
1626 Info:
1628 Either the termination reason of the socket or nosock
1629 (socket Socket did not exist at the time of monitor cre‐
1630 ation).
1631 Making several calls to socket:monitor/1 for the same Socket is
1633 not an error; it results in as many independent monitoring in‐
1634 stances.
1635 number_of() -> integer() >= 0
1637 Returns the number of active sockets.
1639 open(FD) -> {ok, Socket} | {error, Reason}
1641 open(FD, Opts) -> {ok, Socket} | {error, Reason}
1643 Types:
1645 FD = integer()
1647 Opts =
1648 #{domain => domain() | integer(),
1649 type => type() | integer(),
1650 protocol => default | protocol() | integer(),
1651 dup => boolean(),
1652 debug => boolean(),
1653 use_registry => boolean()}
1654 Socket = socket()
1655 Reason = posix() | domain | type | protocol
1656 Creates an endpoint (socket) for communication based on an al‐
1658 ready existing file descriptor. The function attempts to re‐
1659 trieve domain, type and protocol from the system. This is how‐
1660 ever not possible on all platforms, and they should then be
1661 specified in Opts.
1662 The Opts argument is intended for providing extra information
1664 for the open call:
1665 domain:
1667 Which protocol domain is the descriptor of. See also
1668 open/2,3,4.
1669 type:
1671 Which protocol type type is the descriptor of.
1672 See also open/2,3,4.
1674 protocol:
1676 Which protocol is the descriptor of. The atom default is
1677 equivalent to the integer protocol number 0 which means the
1678 default protocol for a given domain and type.
1679 If the protocol can not be retrieved from the platform for
1681 the socket, and protocol is not specified, the default pro‐
1682 tocol is used, which may or may not be correct.
1683 See also open/2,3,4.
1685 dup:
1687 Shall the provided descriptor be duplicated (dup) or not.
1688 Defaults to true.
1689 debug:
1691 Enable or disable debug during the open call.
1692 Defaults to false.
1693 use_registry>:
1695 Enable or disable use of the socket registry for this
1696 socket. This overrides the global value.
1697 Defaults to the global value, see use_registry/1.
1698 Note:
1700 This function should be used with care!
1701 On some platforms it is necessary to provide domain, type and
1703 protocol since they cannot be retreived from the platform.
1704 open(Domain, Type) -> {ok, Socket} | {error, Reason}
1707 open(Domain, Type, Opts) -> {ok, Socket} | {error, Reason}
1709 Types:
1711 Domain = domain() | integer()
1713 Type = type() | integer()
1714 Opts = map()
1715 Socket = socket()
1716 Reason = posix() | protocol
1717 Creates an endpoint (socket) for communication.
1719 The same as open(Domain, Type, default) and open(Domain, Type,
1721 default, Opts) respectively.
1722 open(Domain, Type, Protocol) -> {ok, Socket} | {error, Reason}
1724 open(Domain, Type, Protocol, Opts) ->
1726 {ok, Socket} | {error, Reason}
1727 Types:
1729 Domain = domain() | integer()
1731 Type = type() | integer()
1732 Protocol = default | protocol() | integer()
1733 Opts =
1734 #{netns => string(),
1735 debug => boolean(),
1736 use_registry => boolean()}
1737 Socket = socket()
1738 Reason = posix() | protocol
1739 Creates an endpoint (socket) for communication.
1741 Domain and Type may be integer()s, as defined in the platform's
1743 header files. The same goes for Protocol as defined in the plat‐
1744 form's services(5) database. See also the OS man page for the
1745 library call socket(2).
1746 Note:
1748 For some combinations of Domain and Type the platform has got a
1749 default protocol that can be selected with Protocol = default,
1750 and the platform may allow or require selecting the default pro‐
1751 tocol, a specific protocol, or either.
1752 Examples:
1754 socket:open(inet, stream, tcp):
1756 It is common that for protocol domain and type inet,stream
1757 it is allowed to select the tcp protocol although that
1758 mostly is the default.
1759 socket:open(local, dgram):
1761 It is common that for the protocol domain local it is manda‐
1762 tory to not select a protocol, that is; to select the de‐
1763 fault protocol.
1764 The Opts argument is intended for "other" options. The supported
1767 option(s) are described below:
1768 netns: string():
1770 Used to set the network namespace during the open call. Only
1771 supported on the Linux platform.
1772 debug: boolean():
1774 Enable or disable debug during the open call.
1775 Defaults to false.
1776 use_registry: boolean():
1778 Enable or disable use of the socket registry for this
1779 socket. This overrides the global value.
1780 Defaults to the global value, see use_registry/1.
1781 peername(Socket) -> {ok, SockAddr} | {error, Reason}
1783 Types:
1785 Socket = socket()
1787 SockAddr = sockaddr_recv()
1788 Reason = posix() | closed
1789 Returns the address of the peer connected to the socket.
1791 recv(Socket) ->
1793 {ok, Data} | {error, Reason} | {error, {Reason, Data}}
1794 recv(Socket, Flags) ->
1796 {ok, Data} | {error, Reason} | {error, {Reason, Data}}
1797 recv(Socket, Length) ->
1799 {ok, Data} | {error, Reason} | {error, {Reason, Data}}
1800 recv(Socket, Flags, Timeout :: infinity) ->
1802 {ok, Data} | {error, Reason} | {error, {Reason, Data}}
1803 recv(Socket, Length, Flags) ->
1805 {ok, Data} | {error, Reason} | {error, {Reason, Data}}
1806 recv(Socket, Length, Timeout :: infinity) ->
1808 {ok, Data} | {error, Reason} | {error, {Reason, Data}}
1809 recv(Socket, Length, Flags, Timeout :: infinity) ->
1811 {ok, Data} | {error, Reason} | {error, {Reason, Data}}
1812 Types:
1814 Socket = socket()
1816 Length = integer() >= 0
1817 Flags = [msg_flag() | integer()]
1818 Data = binary()
1819 Reason = posix() | closed | invalid()
1820 Receives data from a socket, waiting for it to arrive.
1822 The argument Length specifies how many bytes to receive, with
1824 the special case 0 meaning "all available".
1825 For a socket of type stream this call will not return until all
1827 requested data can be delivered, or if "all available" data was
1828 requested when the first data chunk arrives.
1829 The message Flags may be symbolic msg_flag()s and/or integer()s,
1831 as in the platform's appropriate header files. The values of all
1832 symbolic flags and integers are or:ed together.
1833 When there is a socket error this function returns {error, Rea‐
1835 son}, or if some data arrived before the error; {error, {Reason,
1836 Data}}.
1837 recv(Socket, Flags, Timeout :: integer() >= 0) ->
1839 {ok, Data} | {error, Reason} | {error, {Reason, Data}}
1840 recv(Socket, Length, Timeout :: integer() >= 0) ->
1842 {ok, Data} | {error, Reason} | {error, {Reason, Data}}
1843 recv(Socket, Length, Flags, Timeout :: integer() >= 0) ->
1845 {ok, Data} | {error, Reason} | {error, {Reason, Data}}
1846 Types:
1848 Socket = socket()
1850 Length = integer() >= 0
1851 Flags = [msg_flag() | integer()]
1852 Data = binary()
1853 Reason = posix() | closed | invalid() | timeout
1854 Receives data from a socket, waiting at most Timeout millisec‐
1856 onds for it to arrive.
1857 The same as infinite time-out recv/1,2,3,4 but returns {error,
1859 timeout} or {error, {timeout, Data}} after Timeout milliseconds,
1860 if the requested data has not been delivered.
1861 recv(Socket, Flags, SelectHandle :: nowait) ->
1863 {ok, Data} |
1864 {select, SelectInfo} |
1865 {select, {SelectInfo, Data}} |
1866 {error, Reason} |
1867 {error, {Reason, Data}}
1868 recv(Socket, Flags, SelectHandle :: select_handle()) ->
1870 {ok, Data} |
1871 {select, SelectInfo} |
1872 {select, {SelectInfo, Data}} |
1873 {error, Reason} |
1874 {error, {Reason, Data}}
1875 recv(Socket, Length, SelectHandle :: nowait) ->
1877 {ok, Data} |
1878 {select, SelectInfo} |
1879 {select, {SelectInfo, Data}} |
1880 {error, Reason} |
1881 {error, {Reason, Data}}
1882 recv(Socket, Length, SelectHandle :: select_handle()) ->
1884 {ok, Data} |
1885 {select, SelectInfo} |
1886 {select, {SelectInfo, Data}} |
1887 {error, Reason} |
1888 {error, {Reason, Data}}
1889 recv(Socket, Length, Flags, SelectHandle :: nowait) ->
1891 {ok, Data} |
1892 {select, SelectInfo} |
1893 {select, {SelectInfo, Data}} |
1894 {error, Reason} |
1895 {error, {Reason, Data}}
1896 recv(Socket, Length, Flags, SelectHandle :: select_handle()) ->
1898 {ok, Data} |
1899 {select, SelectInfo} |
1900 {select, {SelectInfo, Data}} |
1901 {error, Reason} |
1902 {error, {Reason, Data}}
1903 Types:
1905 Socket = socket()
1907 Length = integer() >= 0
1908 Flags = [msg_flag() | integer()]
1909 Data = binary()
1910 SelectInfo = select_info()
1911 Reason = posix() | closed | invalid()
1912 Receives data from a socket, but returns a select continuation
1914 if the data could not be returned immediately.
1915 The same as infinite time-out recv/1,2,3,4 but if the data can‐
1917 not be delivered immediately, the function returns {select, Se‐
1918 lectInfo}, and the caller will then receive a select message,
1919 {'$socket', Socket, select, SelectHandle} ( with the Selec‐
1920 tHandle contained in the SelectInfo ) when data has arrived. A
1921 subsequent call to recv/1,2,3,4 will then return the data.
1922 If the time-out argument is SelectHandle, that term will be con‐
1924 tained in a returned SelectInfo and the corresponding select
1925 message. The SelectHandle is presumed to be unique to this call.
1926 If the time-out argument is nowait, and a SelectInfo is re‐
1928 turned, it will contain a select_handle() generated by the call.
1929 Note that for a socket of type stream, if Length > 0 and only
1931 part of that amount of data is available, the function will re‐
1932 turn {ok, {Data, SelectInfo with partial data. If the caller
1933 doesn't want to wait for more data, it must immediately call
1934 cancel/2 to cancel the operation.
1935 recvfrom(Socket) -> {ok, {Source, Data}} | {error, Reason}
1937 recvfrom(Socket, Flags) -> {ok, {Source, Data}} | {error, Reason}
1939 recvfrom(Socket, BufSz) -> {ok, {Source, Data}} | {error, Reason}
1941 recvfrom(Socket, Flags, Timeout :: infinity) ->
1943 {ok, {Source, Data}} | {error, Reason}
1944 recvfrom(Socket, BufSz, Flags) ->
1946 {ok, {Source, Data}} | {error, Reason}
1947 recvfrom(Socket, BufSz, Timeout :: infinity) ->
1949 {ok, {Source, Data}} | {error, Reason}
1950 recvfrom(Socket, BufSz, Flags, Timeout :: infinity) ->
1952 {ok, {Source, Data}} | {error, Reason}
1953 Types:
1955 Socket = socket()
1957 BufSz = integer() >= 0
1958 Flags = [msg_flag() | integer()]
1959 Source = sockaddr_recv()
1960 Data = binary()
1961 Reason = posix() | closed | invalid()
1962 Receive a message from a socket, waiting for it to arrive.
1964 The function returns when a message is received, or when there
1966 is a socket error. Argument BufSz specifies the number of bytes
1967 for the receive buffer. If the buffer size is too small, the
1968 message will be truncated.
1969 If BufSz is not specified or 0, a default buffer size is used,
1971 which can be set by socket:setopt(Socket, {otp,recvbuf}, BufSz).
1972 If it is impossible to know the appropriate buffer size, it may
1974 be possible to use the receive message flag peek. When this flag
1975 is used, the message is not "consumed" from the underlying buf‐
1976 fers, so another recvfrom/1,2,3,4 call is needed, possibly with
1977 an adjusted buffer size.
1978 The message Flags may be symbolic msg_flag()s and/or integer()s,
1980 as in the platform's appropriate header files. The values of all
1981 symbolic flags and integers are or:ed together.
1982 recvfrom(Socket, Flags, Timeout :: integer() >= 0) ->
1984 {ok, {Source, Data}} | {error, Reason}
1985 recvfrom(Socket, BufSz, Timeout :: integer() >= 0) ->
1987 {ok, {Source, Data}} | {error, Reason}
1988 recvfrom(Socket, BufSz, Flags, Timeout :: integer() >= 0) ->
1990 {ok, {Source, Data}} | {error, Reason}
1991 Types:
1993 Socket = socket()
1995 BufSz = integer() >= 0
1996 Flags = [msg_flag() | integer()]
1997 Source = sockaddr_recv()
1998 Data = binary()
1999 Reason = posix() | closed | invalid() | timeout
2000 Receives a message from a socket, waiting at most Timeout mil‐
2002 liseconds for it to arrive.
2003 The same as infinite time-out recvfrom/1,2,3,4 but returns {er‐
2005 ror, timeout} after Timeout milliseconds, if no message has been
2006 delivered.
2007 recvfrom(Socket, Flags, SelectHandle :: nowait) ->
2009 {ok, {Source, Data}} |
2010 {select, SelectInfo} |
2011 {error, Reason}
2012 recvfrom(Socket, Flags, SelectHandle :: select_handle()) ->
2014 {ok, {Source, Data}} |
2015 {select, SelectInfo} |
2016 {error, Reason}
2017 recvfrom(Socket, BufSz, SelectHandle :: nowait) ->
2019 {ok, {Source, Data}} |
2020 {select, SelectInfo} |
2021 {error, Reason}
2022 recvfrom(Socket, BufSz, SelectHandle :: select_handle()) ->
2024 {ok, {Source, Data}} |
2025 {select, SelectInfo} |
2026 {error, Reason}
2027 recvfrom(Socket, BufSz, Flags, SelectHandle :: nowait) ->
2029 {ok, {Source, Data}} |
2030 {select, SelectInfo} |
2031 {error, Reason}
2032 recvfrom(Socket, BufSz, Flags, SelectHandle :: select_handle()) ->
2034 {ok, {Source, Data}} |
2035 {select, SelectInfo} |
2036 {error, Reason}
2037 Types:
2039 Socket = socket()
2041 BufSz = integer() >= 0
2042 Flags = [msg_flag() | integer()]
2043 Source = sockaddr_recv()
2044 Data = binary()
2045 SelectInfo = select_info()
2046 Reason = posix() | closed | invalid()
2047 Receives a message from a socket, but returns a select continua‐
2049 tion if no message could be returned immediately.
2050 The same as infinite time-out recvfrom/1,2,3,4 but if no mes‐
2052 sage cannot delivered immediately, the function returns {select,
2053 SelectInfo}, and the caller will then receive a select message,
2054 {'$socket', Socket, select, SelectHandle} ( with the Selec‐
2055 tHandle contained in the SelectInfo ) when data has arrived. A
2056 subsequent call to recvfrom/1,2,3,4 will then return the mes‐
2057 sage.
2058 If the time-out argument is SelectHandle, that term will be con‐
2060 tained in a returned SelectInfo and the corresponding select
2061 message. The SelectHandle is presumed to be unique to this call.
2062 If the time-out argument is nowait, and a SelectInfo is re‐
2064 turned, it will contain a select_handle() generated by the call.
2065 If the caller doesn't want to wait for the data, it must immedi‐
2067 ately call cancel/2 to cancel the operation.
2068 recvmsg(Socket) -> {ok, Msg} | {error, Reason}
2070 recvmsg(Socket, Flags) -> {ok, Msg} | {error, Reason}
2072 recvmsg(Socket, Timeout :: infinity) ->
2074 {ok, Msg} | {error, Reason}
2075 recvmsg(Socket, Flags, Timeout :: infinity) ->
2077 {ok, Msg} | {error, Reason}
2078 recvmsg(Socket, BufSz, CtrlSz) -> {ok, Msg} | {error, Reason}
2080 recvmsg(Socket, BufSz, CtrlSz, Timeout :: infinity) ->
2082 {ok, Msg} | {error, Reason}
2083 recvmsg(Socket, BufSz, CtrlSz, Flags, Timeout :: infinity) ->
2085 {ok, Msg} | {error, Reason}
2086 Types:
2088 Socket = socket()
2090 BufSz = CtrlSz = integer() >= 0
2091 Flags = [msg_flag() | integer()]
2092 Msg = msg_recv()
2093 Reason = posix() | closed | invalid()
2094 Receive a message from a socket, waiting for it to arrive.
2096 The function returns when a message is received, or when there
2098 is a socket error. Arguments BufSz and CtrlSz specifies the num‐
2099 ber of bytes for the receive buffer and the control message buf‐
2100 fer. If the buffer size(s) is(are) too small, the message and/or
2101 control message list will be truncated.
2102 If BufSz is not specified or 0, a default buffer size is used,
2104 which can be set by socket:setopt(Socket, {otp,recvbuf}, BufSz).
2105 The same applies to CtrlSz and socket:setopt(Socket, {otp,recvc‐
2106 trlbuf}, CtrlSz).
2107 If it is impossible to know the appropriate buffer size, it may
2109 be possible to use the receive message flag peek. When this flag
2110 is used, the message is not "consumed" from the underlying buf‐
2111 fers, so another recvfrom/1,2,3,4,5 call is needed, possibly
2112 with an adjusted buffer size.
2113 The message Flags may be symbolic msg_flag()s and/or integer()s,
2115 as in the platform's appropriate header files. The values of all
2116 symbolic flags and integers are or:ed together.
2117 recvmsg(Socket, Timeout :: integer() >= 0) ->
2119 {ok, Msg} | {error, Reason}
2120 recvmsg(Socket, Flags, Timeout :: integer() >= 0) ->
2122 {ok, Msg} | {error, Reason}
2123 recvmsg(Socket, BufSz, CtrlSz, Timeout :: integer() >= 0) ->
2125 {ok, Msg} | {error, Reason}
2126 recvmsg(Socket, BufSz, CtrlSz, Flags,
2128 Timeout :: integer() >= 0) ->
2129 {ok, Msg} | {error, Reason}
2130 Types:
2132 Socket = socket()
2134 BufSz = CtrlSz = integer() >= 0
2135 Flags = [msg_flag() | integer()]
2136 Msg = msg_recv()
2137 Reason = posix() | closed | invalid() | timeout
2138 Receives a message from a socket, waiting at most Timeout mil‐
2140 liseconds for it to arrive.
2141 The same as recvmsg/1,2,3,4,5 but returns {error, timeout} after
2143 Timeout milliseconds, if no message has been delivered.
2144 recvmsg(Socket, Timeout :: nowait) ->
2146 {ok, Msg} | {select, SelectInfo} | {error, Reason}
2147 recvmsg(Socket, SelectHandle :: select_handle()) ->
2149 {ok, Msg} | {select, SelectInfo} | {error, Reason}
2150 recvmsg(Socket, Flags, Timeout :: nowait) ->
2152 {ok, Msg} | {select, SelectInfo} | {error, Reason}
2153 recvmsg(Socket, Flags, SelectHandle :: select_handle()) ->
2155 {ok, Msg} | {select, SelectInfo} | {error, Reason}
2156 recvmsg(Socket, BufSz, CtrlSz, SelectHandle :: nowait) ->
2158 {ok, Msg} | {select, SelectInfo} | {error, Reason}
2159 recvmsg(Socket, BufSz, CtrlSz, SelectHandle :: select_handle()) ->
2161 {ok, Msg} | {select, SelectInfo} | {error, Reason}
2162 recvmsg(Socket, BufSz, CtrlSz, Flags, SelectHandle :: nowait) ->
2164 {ok, Msg} | {select, SelectInfo} | {error, Reason}
2165 recvmsg(Socket, BufSz, CtrlSz, Flags,
2167 SelectHandle :: select_handle()) ->
2168 {ok, Msg} | {select, SelectInfo} | {error, Reason}
2169 Types:
2171 Socket = socket()
2173 BufSz = CtrlSz = integer() >= 0
2174 Flags = [msg_flag() | integer()]
2175 Msg = msg_recv()
2176 SelectInfo = select_info()
2177 Reason = posix() | closed | invalid()
2178 Receives a message from a socket, but returns a select continua‐
2180 tion if no message could be returned immediately.
2181 The same as infinite time-out recvfrom/1,2,3,4 but if no mes‐
2183 sage cannot delivered immediately, the function returns {select,
2184 SelectInfo}, and the caller will then receive a select message,
2185 {'$socket', Socket, select, SelectHandle} ( with the Selec‐
2186 tHandle contained in the SelectInfo ) when data has arrived. A
2187 subsequent call to recvmsg/1,2,3,4,5 will then return the data.
2188 If the time-out argument is SelectHandle, that term will be con‐
2190 tained in a returned SelectInfo and the corresponding select
2191 message. The SelectHandle is presumed to be unique to this call.
2192 If the time-out argument is nowait, and a SelectInfo is re‐
2194 turned, it will contain a select_handle() generated by the call.
2195 If the caller doesn't want to wait for the data, it must immedi‐
2197 ately call cancel/2 to cancel the operation.
2198 send(Socket, Data) ->
2200 ok |
2201 {ok, RestData} |
2202 {error, Reason} |
2203 {error, {Reason, RestData}}
2204 send(Socket, Data, Flags) ->
2206 ok |
2207 {ok, RestData} |
2208 {error, Reason} |
2209 {error, {Reason, RestData}}
2210 send(Socket, Data, Timeout :: infinity) ->
2212 ok |
2213 {ok, RestData} |
2214 {error, Reason} |
2215 {error, {Reason, RestData}}
2216 send(Socket, Data, Flags, Timeout :: infinity) ->
2218 ok |
2219 {ok, RestData} |
2220 {error, Reason} |
2221 {error, {Reason, RestData}}
2222 Types:
2224 Socket = socket()
2226 Data = iodata()
2227 Flags = [msg_flag() | integer()]
2228 RestData = binary()
2229 Reason = posix() | closed | invalid()
2230 Sends data on a connected socket, waiting for it to be sent.
2232 This call will not return until the Data has been accepted by
2234 the platform's network layer, or it reports an error.
2235 The message Flags may be symbolic msg_flag()s and/or integer()s,
2237 matching the platform's appropriate header files. The values of
2238 all symbolic flags and integers are or:ed together.
2239 The Data, if it is not a binary(), is copied into one before
2241 calling the platform network API, because a single buffer is re‐
2242 quired. A returned RestData is a sub binary of this data binary.
2243 The return value indicates the result from the platform's net‐
2245 work layer:
2246 ok:
2248 All data has been accepted.
2249 {ok, RestData}:
2251 Not all data has been accepted, but no error has been re‐
2252 ported. RestData is the tail of Data that has not been ac‐
2253 cepted.
2254 This cannot happen for a socket of type stream where a par‐
2256 tially succesful send is retried until the data is either
2257 accepted or there is an error.
2258 For a socket of type dgram this should probably also not
2260 happen since a message that cannot be passed atomically
2261 should render an error.
2262 It is nevertheless possible for the platform's network layer
2264 to return this.
2265 {error, Reason}:
2267 An error has been reported and no data has been accepted.
2268 The posix() Reasons are from the platform's network layer.
2269 closed means that this socket library knows that the socket
2270 is closed, and invalid() means that something about an argu‐
2271 ment is invalid.
2272 {error, {Reason, RestData}} :
2274 An error has been reported but before that some data was ac‐
2275 cepted. RestData is the tail of Data that has not been ac‐
2276 cepted. See {error, Reason} above.
2277 This can only happen for a socket of type stream when a par‐
2279 tially succesful send is retried untill there is an error.
2280 send(Socket, Data, Timeout :: integer() >= 0) ->
2282 ok |
2283 {ok, RestData} |
2284 {error, Reason | timeout} |
2285 {error, {Reason | timeout, RestData}}
2286 send(Socket, Data, Flags, Timeout :: integer() >= 0) ->
2288 ok |
2289 {ok, RestData} |
2290 {error, Reason | timeout} |
2291 {error, {Reason | timeout, RestData}}
2292 Types:
2294 Socket = socket()
2296 Data = iodata()
2297 Flags = [msg_flag() | integer()]
2298 RestData = binary()
2299 Reason = posix() | closed | invalid()
2300 Sends data on a connected socket, waiting at most Timeout mil‐
2302 liseconds for it to be sent.
2303 The same as infinite time-out send/2,3,4 but returns {error,
2305 timeout} or {error, {timeout, RestData}} after Timeout millisec‐
2306 onds, if no Data or only some of it was accepted by the plat‐
2307 form's network layer.
2308 send(Socket, Data, SelectHandle :: nowait) ->
2310 ok |
2311 {ok, RestData} |
2312 {select, SelectInfo} |
2313 {select, {SelectInfo, RestData}} |
2314 {error, Reason}
2315 send(Socket, Data, SelectHandle :: select_handle()) ->
2317 ok |
2318 {ok, RestData} |
2319 {select, SelectInfo} |
2320 {select, {SelectInfo, RestData}} |
2321 {error, Reason}
2322 send(Socket, Data, Flags, SelectHandle :: nowait) ->
2324 ok |
2325 {ok, RestData} |
2326 {select, SelectInfo} |
2327 {select, {SelectInfo, RestData}} |
2328 {error, Reason}
2329 send(Socket, Data, Flags, SelectHandle :: select_handle()) ->
2331 ok |
2332 {ok, RestData} |
2333 {select, SelectInfo} |
2334 {select, {SelectInfo, RestData}} |
2335 {error, Reason}
2336 Types:
2338 Socket = socket()
2340 Data = iodata()
2341 Flags = [msg_flag() | integer()]
2342 RestData = binary()
2343 SelectInfo = select_info()
2344 Reason = posix() | closed | invalid()
2345 Sends data on a connected socket, but returns a select continua‐
2347 tion if the data could not be sent immediately.
2348 The same as infinite time-out send/2,3 but if the data is not
2350 immediately accepted by the platform network layer, the function
2351 returns {select, SelectInfo}, and the caller will then receive a
2352 select message, {'$socket', Socket, select, SelectHandle} ( with
2353 the SelectHandle that was contained in the SelectInfo ) when
2354 there is room for more data. A subsequent call to send/2-4 will
2355 then send the data.
2356 If SelectHandle is a select_handle(), that term will be con‐
2358 tained in a returned SelectInfo and the corresponding select
2359 message. The SelectHandle is presumed to be unique to this call.
2360 If SelectHandle is nowait, and a SelectInfo is returned, it will
2362 contain a select_handle() generated by the call.
2363 If some of the data was sent, the function will return {ok,
2365 {RestData, SelectInfo}, which can only happen for a socket of
2366 type stream. If the caller does not want to wait to send the
2367 rest of the data, it should immediately cancel the operation
2368 with cancel/2.
2369 send(Socket, Data, Cont) ->
2371 ok |
2372 {ok, RestData} |
2373 {error, Reason} |
2374 {error, {Reason, RestData}}
2375 send(Socket, Data, Cont, Timeout :: infinity) ->
2377 ok |
2378 {ok, RestData} |
2379 {error, Reason} |
2380 {error, {Reason, RestData}}
2381 send(Socket, Data, Cont, Timeout :: integer() >= 0) ->
2383 ok |
2384 {ok, RestData} |
2385 {error, Reason | timeout} |
2386 {error, {Reason | timeout, RestData}}
2387 send(Socket, Data, Cont, SelectHandle :: nowait) ->
2389 ok |
2390 {ok, RestData} |
2391 {select, SelectInfo} |
2392 {select, {SelectInfo, RestData}} |
2393 {error, Reason}
2394 send(Socket, Data, Cont, SelectHandle :: select_handle()) ->
2396 ok |
2397 {ok, RestData} |
2398 {select, SelectInfo} |
2399 {select, {SelectInfo, RestData}} |
2400 {error, Reason}
2401 Types:
2403 Socket = socket()
2405 Data = iodata()
2406 Cont = select_info()
2407 RestData = binary()
2408 SelectInfo = select_info()
2409 Reason = posix() | closed | invalid()
2410 Continues sending data on a connected socket, where the send op‐
2412 eration was initiated by send/3,4 that returned a SelectInfo
2413 continuation. Otherwise like infinite time-out send/2,3,4 ,
2414 limited time-out send/3,4 or nowait send/3,4 respectively.
2415 Cont is the SelectInfo that was returned from the previous
2417 send() call.
2418 If Data is not a binary(), it will be copied into one, again.
2420 The return value indicates the result from the platform's net‐
2422 work layer. See send/2,3,4 and nowait send/3,4.
2423 sendmsg(Socket, Msg) ->
2425 ok |
2426 {ok, RestData} |
2427 {error, Reason} |
2428 {error, {Reason, RestData}}
2429 sendmsg(Socket, Msg, Flags) ->
2431 ok |
2432 {ok, RestData} |
2433 {error, Reason} |
2434 {error, {Reason, RestData}}
2435 sendmsg(Socket, Msg, Timeout :: infinity) ->
2437 ok |
2438 {ok, RestData} |
2439 {error, Reason} |
2440 {error, {Reason, RestData}}
2441 sendmsg(Socket, Msg, Flags, Timeout :: infinity) ->
2443 ok |
2444 {ok, RestData} |
2445 {error, Reason} |
2446 {error, {Reason, RestData}}
2447 Types:
2449 Socket = socket()
2451 Msg = msg_send()
2452 Flags = [msg_flag() | integer()]
2453 RestData = erlang:iovec()
2454 Reason = posix() | closed | invalid()
2455 Sends a message on a socket, waiting for it to be sent.
2457 The destination, if needed, that is: if the socket is not con‐
2459 nected, is provided in Msg, which also contains the data to send
2460 as a list of binaries. Msg may also contain an list of optional
2461 control messages (depending on what the protocol and platform
2462 supports).
2463 For a connected socket no address field should be present in
2465 Msg, the platform may return an error or ignore one.
2466 The message data is given to to the platform's network layer in
2468 the form of an I/O vector without copying the content. If the
2469 number of elements in the I/O vector is larger than allowed on
2470 the platform (reported in the iov_max field from info/0), on a
2471 socket of type stream the send is iterated over all elements,
2472 but for other socket types the call fails.
2473 This call will not return until the data has been handed over to
2475 the platform's network layer, or when it reports an error.
2476 The message Flags may be symbolic msg_flag()s and/or integer()s,
2478 matching the platform's appropriate header files. The values of
2479 all symbolic flags and integers are or:ed together.
2480 The return value indicates the result from the platform's net‐
2482 work layer. See send/2,3,4.
2483 sendmsg(Socket, Msg, Timeout :: integer() >= 0) ->
2485 ok |
2486 {ok, RestData} |
2487 {error, Reason | timeout} |
2488 {error, {Reason | timeout, RestData}}
2489 sendmsg(Socket, Msg, Flags, Timeout :: integer() >= 0) ->
2491 ok |
2492 {ok, RestData} |
2493 {error, Reason | timeout} |
2494 {error, {Reason | timeout, RestData}}
2495 Types:
2497 Socket = socket()
2499 Msg = msg_send()
2500 Flags = [msg_flag() | integer()]
2501 RestData = erlang:iovec()
2502 Reason = posix() | closed | invalid()
2503 Sends a message on a socket, waiting at most Timeout millisec‐
2505 onds for it to be sent.
2506 The same as infinite time-out sendmsg/2,3,4 but returns {error,
2508 timeout} or {error, {timeout, RestData}} after Timeout millisec‐
2509 onds, if no data or only some of it was accepted by the plat‐
2510 form's network layer.
2511 sendmsg(Socket, Msg, Timeout :: nowait) ->
2513 ok |
2514 {ok, RestData} |
2515 {select, SelectInfo} |
2516 {select, {SelectInfo, RestData}} |
2517 {error, Reason} |
2518 {error, {Reason, RestData}}
2519 sendmsg(Socket, Msg, SelectHandle :: select_handle()) ->
2521 ok |
2522 {ok, RestData} |
2523 {select, SelectInfo} |
2524 {select, {SelectInfo, RestData}} |
2525 {error, Reason} |
2526 {error, {Reason, RestData}}
2527 sendmsg(Socket, Msg, Flags, SelectHandle :: nowait) ->
2529 ok |
2530 {ok, RestData} |
2531 {select, SelectInfo} |
2532 {select, {SelectInfo, RestData}} |
2533 {error, Reason} |
2534 {error, {Reason, RestData}}
2535 sendmsg(Socket, Msg, Flags, SelectHandle :: select_handle()) ->
2537 ok |
2538 {ok, RestData} |
2539 {select, SelectInfo} |
2540 {select, {SelectInfo, RestData}} |
2541 {error, Reason} |
2542 {error, {Reason, RestData}}
2543 Types:
2545 Socket = socket()
2547 Msg = msg_send()
2548 Flags = [msg_flag() | integer()]
2549 RestData = erlang:iovec()
2550 SelectInfo = select_info()
2551 Reason = posix() | closed | invalid()
2552 Sends a message on a socket, but returns a select continuation
2554 if the data could not be sent immediately.
2555 The same as infinity time-out sendmsg/2,3 but if the data is
2557 not immediately accepted by the platform network layer, the
2558 function returns {select, SelectInfo}, and the caller will then
2559 receive a select message, {'$socket', Socket, select, Selec‐
2560 tHandle} ( with the SelectHandle that was contained in the Se‐
2561 lectInfo ) when there is room for more data. A subsequent call
2562 to sendmsg/2-4 will then send the data.
2563 If SelectHandle, is a select_handle(), that term will be con‐
2565 tained in a returned SelectInfo and the corresponding select
2566 message. The SelectHandle is presumed to be unique to this call.
2567 If SelectHandle is nowait, and a SelectInfo is returned, it will
2569 contain a select_handle() generated by the call.
2570 If some of the data was sent, the function will return {ok,
2572 {RestData, SelectInfo}, which can only happen for a socket of
2573 type stream. If the caller does not want to wait to send the
2574 rest of the data, it should immediately cancel the operation
2575 with cancel/2.
2576 sendmsg(Socket, Data, Cont) ->
2578 ok |
2579 {ok, RestData} |
2580 {error, Reason} |
2581 {error, {Reason, RestData}}
2582 sendmsg(Socket, Data, Cont, Timeout :: infinity) ->
2584 ok |
2585 {ok, RestData} |
2586 {error, Reason} |
2587 {error, {Reason, RestData}}
2588 sendmsg(Socket, Data, Cont, Timeout :: integer() >= 0) ->
2590 ok |
2591 {ok, RestData} |
2592 {error, Reason | timeout} |
2593 {error, {Reason | timeout, RestData}}
2594 sendmsg(Socket, Data, Cont, SelectHandle :: nowait) ->
2596 ok |
2597 {ok, RestData} |
2598 {select, SelectInfo} |
2599 {select, {SelectInfo, RestData}} |
2600 {error, Reason} |
2601 {error, {Reason, RestData}}
2602 sendmsg(Socket, Data, Cont, SelectHandle :: select_handle()) ->
2604 ok |
2605 {ok, RestData} |
2606 {select, SelectInfo} |
2607 {select, {SelectInfo, RestData}} |
2608 {error, Reason} |
2609 {error, {Reason, RestData}}
2610 Types:
2612 Socket = socket()
2614 Data = msg_send() | erlang:iovec()
2615 Cont = select_info()
2616 RestData = erlang:iovec()
2617 SelectInfo = select_info()
2618 Reason = posix() | closed | invalid()
2619 Continues sending a message data on a socket, where the send op‐
2621 eration was initiated by sendmsg/3,4 that returned a SelectInfo
2622 continuation. Otherwise like infinite time-out sendmsg/2,3,4 ,
2623 limited time-out sendmsg/3,4 or nowait sendmsg/3,4 respec‐
2624 tively.
2625 Cont is the SelectInfo that was returned from the previous
2627 sendmsg() call.
2628 The return value indicates the result from the platform's net‐
2630 work layer. See send/2,3,4 and nowait sendmsg/3,4.
2631 sendto(Socket, Data, Dest) ->
2633 ok |
2634 {ok, RestData} |
2635 {error, Reason} |
2636 {error, {Reason, RestData}}
2637 sendto(Socket, Data, Dest, Flags) ->
2639 ok |
2640 {ok, RestData} |
2641 {error, Reason} |
2642 {error, {Reason, RestData}}
2643 sendto(Socket, Data, Dest, Timeout :: infinity) ->
2645 ok |
2646 {ok, RestData} |
2647 {error, Reason} |
2648 {error, {Reason, RestData}}
2649 sendto(Socket, Data, Dest, Flags, Timeout :: infinity) ->
2651 ok |
2652 {ok, RestData} |
2653 {error, Reason} |
2654 {error, {Reason, RestData}}
2655 Types:
2657 Socket = socket()
2659 Data = iodata()
2660 Dest = sockaddr()
2661 Flags = [msg_flag() | integer()]
2662 RestData = binary()
2663 Reason = posix() | closed | invalid()
2664 Sends data on a socket, to the specified destination, waiting
2666 for it to be sent.
2667 This call will not return until the data has been accepted by
2669 the platform's network layer, or it reports an error.
2670 If this call is used on a connection mode socket or on a con‐
2672 nected socket, the platforms's network layer may return an error
2673 or ignore the destination address.
2674 The message Flags may be symbolic msg_flag()s and/or integer()s,
2676 matching the platform's appropriate header files. The values of
2677 all symbolic flags and integers are or:ed together.
2678 The return value indicates the result from the platform's net‐
2680 work layer. See send/2,3,4.
2681 sendto(Socket, Data, Dest, Timeout :: integer() >= 0) ->
2683 ok |
2684 {ok, RestData} |
2685 {error, Reason | timeout} |
2686 {error, {Reason | timeout, RestData}}
2687 sendto(Socket, Data, Dest, Flags, Timeout :: integer() >= 0) ->
2689 ok |
2690 {ok, RestData} |
2691 {error, Reason | timeout} |
2692 {error, {Reason | timeout, RestData}}
2693 Types:
2695 Socket = socket()
2697 Data = iodata()
2698 Dest = sockaddr()
2699 Flags = [msg_flag() | integer()]
2700 RestData = binary()
2701 Reason = posix() | closed | invalid()
2702 Sends data on a socket, waiting at most Timeout milliseconds for
2704 it to be sent.
2705 The same as infinite time-out sendto/3,4,5 but returns {error,
2707 timeout} or {error, {timeout, RestData}} after Timeout millisec‐
2708 onds, if no Data or only some of it was accepted by the plat‐
2709 form's network layer.
2710 sendto(Socket, Data, Dest, SelectHandle :: nowait) ->
2712 ok |
2713 {ok, RestData} |
2714 {select, SelectInfo} |
2715 {select, {SelectInfo, RestData}} |
2716 {error, Reason}
2717 sendto(Socket, Data, Dest, SelectHandle :: select_handle()) ->
2719 ok |
2720 {ok, RestData} |
2721 {select, SelectInfo} |
2722 {select, {SelectInfo, RestData}} |
2723 {error, Reason}
2724 sendto(Socket, Data, Dest, Flags, SelectHandle :: nowait) ->
2726 ok |
2727 {ok, RestData} |
2728 {select, SelectInfo} |
2729 {select, {SelectInfo, RestData}} |
2730 {error, Reason}
2731 sendto(Socket, Data, Dest, Flags, SelectHandle :: select_handle()) ->
2733 ok |
2734 {ok, RestData} |
2735 {select, SelectInfo} |
2736 {select, {SelectInfo, RestData}} |
2737 {error, Reason}
2738 Types:
2740 Socket = socket()
2742 Data = iodata()
2743 Dest = sockaddr()
2744 Flags = [msg_flag() | integer()]
2745 RestData = binary()
2746 SelectInfo = select_info()
2747 Reason = posix() | closed | invalid()
2748 Sends data on a socket, but returns a select continuation if the
2750 data could not be sent immediately.
2751 The same as infinity time-out sendto/3,4 but if the data is not
2753 immediately accepted by the platform network layer, the function
2754 returns {select, SelectInfo}, and the caller will then receive a
2755 select message, {'$socket', Socket, select, SelectHandle} ( with
2756 the SelectHandle that was contained in the SelectInfo ) when
2757 there is room for more data. A subsequent call to sendto/3-5
2758 will then send the data.
2759 If SelectHandle is a select_handle(), that term will be con‐
2761 tained in a returned SelectInfo and the corresponding select
2762 message. The SelectHandle is presumed to be unique to this call.
2763 If SelectHandle is nowait, and a SelectInfo is returned, it will
2765 contain a select_handle() generated by the call.
2766 If some of the data was sent, the function will return {ok,
2768 {RestData, SelectInfo}, which can only happen for a socket of
2769 type stream. If the caller does not want to wait to send the
2770 rest of the data, it should immediately cancel the operation
2771 with cancel/2.
2772 sendto(Socket, Data, Cont) ->
2774 ok |
2775 {ok, RestData} |
2776 {error, Reason} |
2777 {error, {Reason, RestData}}
2778 sendto(Socket, Data, Cont, Timeout :: infinity) ->
2780 ok |
2781 {ok, RestData} |
2782 {error, Reason} |
2783 {error, {Reason, RestData}}
2784 sendto(Socket, Data, Cont, Timeout :: integer() >= 0) ->
2786 ok |
2787 {ok, RestData} |
2788 {error, Reason | timeout} |
2789 {error, {Reason | timeout, RestData}}
2790 sendto(Socket, Data, Cont, SelectHandle :: nowait) ->
2792 ok |
2793 {ok, RestData} |
2794 {select, SelectInfo} |
2795 {select, {SelectInfo, RestData}} |
2796 {error, Reason}
2797 sendto(Socket, Data, Cont, SelectHandle :: select_handle()) ->
2799 ok |
2800 {ok, RestData} |
2801 {select, SelectInfo} |
2802 {select, {SelectInfo, RestData}} |
2803 {error, Reason}
2804 Types:
2806 Socket = socket()
2808 Data = iodata()
2809 Cont = select_info()
2810 RestData = binary()
2811 SelectInfo = select_info()
2812 Reason = posix() | closed | invalid()
2813 Continues sending data on a socket, where the send operation was
2815 initiated by sendto/4,5 that returned a SelectInfo continuation.
2816 Otherwise like infinite time-out sendto/3,4,5 , limited time-
2817 out sendto/4,5 or nowait sendto/4,5 respectively.
2818 Cont is the SelectInfo that was returned from the previous
2820 sendto() call.
2821 If Data is not a binary(), it will be copied into one, again.
2823 The return value indicates the result from the platform's net‐
2825 work layer. See send/2,3,4 and nowait sendto/4,5.
2826 sendfile(Socket, FileHandle, Offset, Count, Timeout :: infinity) ->
2828 {ok, BytesSent} |
2829 {error, Reason} |
2830 {error, {Reason, BytesSent}}
2831 Types:
2833 Socket = socket()
2835 FileHandle = file:fd()
2836 Offset = integer()
2837 Count = BytesSent = integer() >= 0
2838 Reason = posix() | closed | invalid()
2839 Sends file data on a socket, to the specified destination, wait‐
2841 ing for it to be sent ("infinite" time-out).
2842 The FileHandle must refer to an open raw file as described in
2844 file:open/2.
2845 This call will not return until the data has been accepted by
2847 the platform's network layer, or it reports an error.
2848 The Offset argument is the file offset to start reading from.
2850 The default value is 0.
2851 The Count argument is the number of bytes to transfer from File‐
2853 Handle to Socket. If Count =:= 0 (the default) the transfer
2854 stops at the end of file.
2855 The return value indicates the result from the platform's net‐
2857 work layer:
2858 {ok, BytesSent}:
2860 The transfer completed succesfully after BytesSent bytes of
2861 data.
2862 {error, Reason}:
2864 An error has been reported and no data has been transferred.
2865 The posix() Reasons are from the platform's network layer.
2866 closed means that this socket library knows that the socket
2867 is closed, and invalid() means that something about an argu‐
2868 ment is invalid.
2869 {error, {Reason, BytesSent}} :
2871 An error has been reported but before that some data was
2872 transferred. See {error, Reason} and {ok, BytesSent} above.
2873 sendfile(Socket, FileHandle, Offset, Count,
2875 Timeout :: integer() >= 0) ->
2876 {ok, BytesSent} |
2877 {error, Reason | timeout} |
2878 {error, {Reason | timeout, BytesSent}}
2879 Types:
2881 Socket = socket()
2883 FileHandle = file:fd()
2884 Offset = integer()
2885 Count = BytesSent = integer() >= 0
2886 Reason = posix() | closed | invalid()
2887 Sends file data on a socket, waiting at most Timeout millisec‐
2889 onds for it to be sent (limited time-out).
2890 The same as "infinite" time-out sendfile/5 but returns {error,
2892 timeout} or {error, {timeout, BytesSent}} after Timeout mil‐
2893 liseconds, if not all file data was transferred by the plat‐
2894 form's network layer.
2895 sendfile(Socket, FileHandle, Offset, Count,
2897 SelectHandle :: nowait) ->
2898 {ok, BytesSent} |
2899 {select, SelectInfo} |
2900 {select, {SelectInfo, BytesSent}} |
2901 {error, Reason}
2902 sendfile(Socket, FileHandle, Offset, Count,
2904 SelectHandle :: select_handle()) ->
2905 {ok, BytesSent} |
2906 {select, SelectInfo} |
2907 {select, {SelectInfo, BytesSent}} |
2908 {error, Reason}
2909 Types:
2911 Socket = socket()
2913 FileHandle = file:fd()
2914 Offset = integer()
2915 Count = BytesSent = integer() >= 0
2916 SelectInfo = select_info()
2917 Reason = posix() | closed | invalid()
2918 Sends file data on a socket, but returns a select continuation
2920 if the data could not be sent immediately (nowait).
2921 The same as "infinite" time-out sendfile/5 but if the data is
2923 not immediately accepted by the platform network layer, the
2924 function returns {select, SelectInfo}, and the caller will then
2925 receive a select message, {'$socket', Socket, select, Selec‐
2926 tHandle} ( with the SelectHandle that was contained in the Se‐
2927 lectInfo ) when there is room for more data. Then a call to
2928 sendfile/3 with SelectInfo as the second argument will continue
2929 the data transfer.
2930 If SelectHandle is a select_handle(), that term will be con‐
2932 tained in a returned SelectInfo and the corresponding select
2933 message. The SelectHandle is presumed to be unique to this call.
2934 If SelectHandle is nowait, and a SelectInfo is returned, it will
2936 contain a select_handle() generated by the call.
2937 If some file data was sent, the function will return {ok,
2939 {BytesSent, SelectInfo}. If the caller does not want to wait to
2940 send the rest of the data, it should immediately cancel the op‐
2941 eration with cancel/2.
2942 sendfile(Socket, Cont, Offset, Count, Timeout :: infinity) ->
2944 {ok, BytesSent} |
2945 {error, Reason} |
2946 {error, {Reason, BytesSent}}
2947 sendfile(Socket, Cont, Offset, Count,
2949 Timeout :: integer() >= 0) ->
2950 {ok, BytesSent} |
2951 {error, Reason | timeout} |
2952 {error, {Reason | timeout, BytesSent}}
2953 sendfile(Socket, Cont, Offset, Count, SelectHandle :: nowait) ->
2955 {ok, BytesSent} |
2956 {select, SelectInfo} |
2957 {select, {SelectInfo, BytesSent}} |
2958 {error, Reason}
2959 sendfile(Socket, Cont, Offset, Count,
2961 SelectHandle :: select_handle()) ->
2962 {ok, BytesSent} |
2963 {select, SelectInfo} |
2964 {select, {SelectInfo, BytesSent}} |
2965 {error, Reason}
2966 Types:
2968 Socket = socket()
2970 Cont = select_info()
2971 Offset = integer()
2972 Count = BytesSent = integer() >= 0
2973 SelectInfo = select_info()
2974 Reason = posix() | closed | invalid()
2975 Continues sending file data on a socket, where the send opera‐
2977 tion was initiated by sendfile/3,5 that returned a SelectInfo
2978 continuation. Otherwise like "infinite" time-out sendfile/5 ,
2979 limited time-out sendfile/5 or nowait sendfile/5 respectively.
2980 Cont is the SelectInfo that was returned from the previous send‐
2982 file() call.
2983 The return value indicates the result from the platform's net‐
2985 work layer. See "infinite" time-out sendfile/5.
2986 sendfile(Socket, FileHandle, Offset, Count) -> Result
2988 Types:
2990 Socket = socket()
2992 FileHandle = file:fd()
2993 Offset = integer()
2994 Count = integer() >= 0
2995 The same as sendfile(Socket, FileHandle, Offset, Count, infin‐
2997 ity), that is: send the file data at Offset and Count to the
2998 socket, without time-out other than from the platform's network
2999 stack.
3000 sendfile(Socket, FileHandle, Timeout) -> Result
3002 Types:
3004 Socket = socket()
3006 FileHandle = file:fd()
3007 Timeout = timeout() | 'nowait' | select_handle()
3008 Depending on the Timeout argument; the same as sendfile(Socket,
3010 FileHandle, 0, 0, infinity), sendfile(Socket, FileHandle, 0,
3011 0, Timeout), or sendfile(Socket, FileHandle, 0, 0, Selec‐
3012 tHandle), that is: send all data in the file to the socket,
3013 with the given Timeout.
3014 sendfile(Socket, FileHandle) -> Result
3016 Types:
3018 Socket = socket()
3020 FileHandle = file:fd()
3021 The same as sendfile(Socket, FileHandle, 0, 0, infinity), that
3023 is: send all data in the file to the socket, without time-out
3024 other than from the platform's network stack.
3025 setopt(Socket :: socket(),
3027 SocketOption :: {Level :: otp, Opt :: otp_socket_option()},
3028 Value :: term()) ->
3029 ok | {error, invalid() | closed}
3030 Sets a socket option in the protocol level otp, which is this
3032 implementation's level above the OS protocol layers.
3033 See the type otp_socket_option() for a description of the op‐
3035 tions on this level.
3036 setopt(Socket :: socket(),
3038 SocketOption :: socket_option(),
3039 Value :: term()) ->
3040 ok | {error, posix() | invalid() | closed}
3041 Set a socket option in one of the OS's protocol levels. See the
3043 type socket_option() for which options that this implementation
3044 knows about, how they are related to option names in the OS, and
3045 if there are known pecularities with any of them.
3046 What options are valid depends on what kind of socket it is (do‐
3048 main(), type() and protocol()).
3049 See the socket options chapter of the users guide for more
3051 info.
3052 Note:
3054 Not all options are valid, nor possible to set, on all plat‐
3055 forms. That is, even if "we" support an option; it does not mean
3056 that the underlying OS does.
3057 setopt(Socket, Level, Opt, Value) -> ok | {error, Reason}
3060 Types:
3062 Socket = socket()
3064 Value = term()
3065 Reason = inet:posix() | invalid() | closed
3066 Backwards compatibility function.
3068 The same as setopt(Socket, {Level, Opt}, Value)
3070 setopt_native(Socket :: socket(),
3072 SocketOption ::
3073 socket_option() |
3074 {Level :: level() | (NativeLevel :: integer()),
3075 NativeOpt :: integer()},
3076 Value :: native_value()) ->
3077 ok | {error, posix() | invalid() | closed}
3078 Sets a socket option that may be unknown to our implementation,
3080 or that has a type not compatible with our implementation, that
3081 is; in "native mode".
3082 If Value is an integer() it will be used as a C type (int), if
3084 it is a boolean() it will be used as a C type (int) with the C
3085 implementations values for false or true, and if it is a bi‐
3086 nary() its content and size will be used as the option value.
3087 The socket option may be specified with an ordinary socket_op‐
3089 tion() tuple, with a known Level = level() and an integer Na‐
3090 tiveOpt, or with both an integer NativeLevel and NativeOpt.
3091 What options are valid depends on what kind of socket it is (do‐
3093 main(), type() and protocol()).
3094 The integer values for NativeLevel and NativeOpt as well as the
3096 encoding of Value has to be deduced from the header files for
3097 the running system.
3098 shutdown(Socket, How) -> ok | {error, Reason}
3100 Types:
3102 Socket = socket()
3104 How = read | write | read_write
3105 Reason = posix() | closed
3106 Shut down all or part of a full-duplex connection.
3108 sockname(Socket) -> {ok, SockAddr} | {error, Reason}
3110 Types:
3112 Socket = socket()
3114 SockAddr = sockaddr_recv()
3115 Reason = posix() | closed
3116 Returns the current address to which the socket is bound.
3118 supports() ->
3120 [{Key1 :: term(),
3121 boolean() |
3122 [{Key2 :: term(),
3123 boolean() | [{Key3 :: term(), boolean()}]}]}]
3124 supports(Key1 :: term()) ->
3126 [{Key2 :: term(),
3127 boolean() | [{Key3 :: term(), boolean()}]}]
3128 supports(Key1 :: term(), Key2 :: term()) ->
3130 [{Key3 :: term(), boolean()}]
3131 These functions function retreives information about what the
3133 platform supports, such which platform features or which socket
3134 options, are supported.
3135 For keys other than the known the empty list is returned, Note
3137 that in a future version or on a different platform there might
3138 be more supported items.
3139 supports():
3141 Returns a list of {Key1, supports(Key1)} tuples for every
3142 Key1 described in supports/1 and {Key1, boolean()} tuples
3143 for each of the following keys:
3144 sctp:
3146 SCTP support
3147 ipv6:
3149 IPv6 support
3150 local:
3152 Unix Domain sockets support (AF_UNIX | AF_LOCAL)
3153 netns:
3155 Network Namespaces support (Linux, setns(2))
3156 sendfile:
3158 Sendfile support (sendfile(2))
3159 supports(msg_flags = Key1):
3161 Returns a list of {Flag, boolean()} tuples for every Flag in
3162 msg_flag() with the boolean() indicating if the flag is sup‐
3163 ported on this platform.
3164 supports(protocols = Key1):
3166 Returns a list of {Name :: atom(), boolean()} tuples for ev‐
3167 ery Name in protocol() with the boolean() indicating if the
3168 protocol is supported on this platform.
3169 supports(options = Key1):
3171 Returns a list of {SocketOption, boolean()} tuples for every
3172 SocketOption in socket_option() with the boolean() indicat‐
3173 ing if the socket option is supported on this platform.
3174 supports(options = Key1, Key2) :
3176 For a Key2 in level() returns a list of {Opt, boolean()} tu‐
3177 ples for all known socket options Opt on that Level =:=
3178 Key2, and the boolean() indicating if the socket option is
3179 supported on this platform. See setopt/3 and getopt/2.
3180 use_registry(D :: boolean()) -> ok
3182 Globally change if the socket registry is to be used or not.
3184 Note that its still possible to override this explicitly when
3185 creating an individual sockets, see open/2 or open/4 for more
3186 info (use the Extra argument).
3187 which_sockets() -> [socket()]
3189 which_sockets(FilterRule) -> [socket()]
3191 Types:
3193 FilterRule =
3195 inet | inet6 | local | stream | dgram | seqpacket | sctp
3196 |
3197 tcp | udp |
3198 pid() |
3199 fun((socket_info()) -> boolean())
3200 Returns a list of all sockets, according to the filter rule.
3202 There are several pre-made filter rule(s) and one general:
3204 inet | inet6:
3206 Selection based on the domain of the socket.
3207 Only a subset is valid.
3208 stream | dgram | seqpacket:
3210 Selection based on the type of the socket.
3211 Only a subset is valid.
3212 sctp | tcp | udp:
3214 Selection based on the protocol of the socket.
3215 Only a subset is valid.
3216 pid():
3218 Selection base on which sockets has this pid as Controlling
3219 Process.
3220 fun((socket_info()) -> boolean()):
3222 The general filter rule.
3223 A fun that takes the socket info and returns a boolean()
3224 (true if the socket sould be included and false if should
3225 not).
3226
3228 client(SAddr, SPort) ->
3229 {ok, Sock} = socket:open(inet, stream, tcp),
3230 ok = socket:connect(Sock, #{family => inet,
3231 addr => SAddr,
3232 port => SPort}),
3233 Msg = <<"hello">>,
3234 ok = socket:send(Sock, Msg),
3235 ok = socket:shutdown(Sock, write),
3236 {ok, Msg} = socket:recv(Sock),
3237 ok = socket:close(Sock).
3238 server(Addr, Port) ->
3240 {ok, LSock} = socket:open(inet, stream, tcp),
3241 ok = socket:bind(LSock, #{family => inet,
3242 port => Port,
3243 addr => Addr}),
3244 ok = socket:listen(LSock),
3245 {ok, Sock} = socket:accept(LSock),
3246 {ok, Msg} = socket:recv(Sock),
3247 ok = socket:send(Sock, Msg),
3248 ok = socket:close(Sock),
3249 ok = socket:close(LSock).
3250Ericsson AB kernel 8.1.3 socket(3)