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 ioctl(Socket, GetRequest) -> {ok, IFConf} | {error, Reason}
1580 Types:
1582 Socket = socket()
1584 GetRequest = gifconf
1585 IFConf = [#{name := string, addr := sockaddr()}]
1586 Reason = posix() | closed
1587 Retrieve socket (device) parameters.
1589 ioctl(Socket, GetRequest, NameOrIndex) ->
1591 {ok, Result} | {error, Reason}
1592 Types:
1594 Socket = socket()
1596 GetRequest =
1597 gifname | gifindex | gifaddr | gifdstaddr | gifbrdaddr |
1598 gifnetmask | gifhwaddr | gifmtu | giftxqlen | gifflags
1599 NameOrIndex = string() | integer()
1600 Result = term()
1601 Reason = posix() | closed
1602 Retrieve socket (device) parameters. This function retreives a
1604 specific parameter, according to GetRequest argument. The third
1605 argument is the (lookup) "key", identifying the interface (usu‐
1606 ally the name of the interface).
1607 gifname:
1609 Get the name of the interface with the specified index (in‐
1610 teger()).
1611 Result, name of the interface, is a string().
1613 gifindex:
1615 Get the index of the interface with the specified name.
1616 Result, interface index, is a integer().
1618 gifaddr:
1620 Get the address of the interface with the specified name.
1621 Result, address of the interface, is a socket:sockaddr().
1622 gifdstaddr:
1624 Get the destination address of the point-to-point interface
1625 with the specified name.
1626 Result, destination address of the interface, is a
1628 socket:sockaddr().
1629 gifbrdaddr:
1631 Get the droadcast address for the interface with the speci‐
1632 fied name.
1633 Result, broadcast address of the interface, is a
1635 socket:sockaddr().
1636 gifnetmask:
1638 Get the network mask for the interface with the specified
1639 name.
1640 Result, network mask of the interface, is a socket:sock‐
1642 addr().
1643 gifhwaddr:
1645 Get the hardware address for the interface with the speci‐
1646 fied name.
1647 Result, hardware address of the interface, is a socket:sock‐
1649 addr(). The family field contains the 'ARPHRD' device type
1650 (or an integer).
1651 gifmtu:
1653 Get the MTU (Maximum Transfer Unit) for the interface with
1654 the specified name.
1655 Result, MTU of the interface, is an integer().
1657 giftxqlen:
1659 Get the transmit queue length of the interface with the
1660 specified name.
1661 Result, transmit queue length of the interface, is an inte‐
1663 ger().
1664 gifflags:
1666 Get the active flag word of the interface with the specified
1667 name.
1668 Result, the active flag word of the interface, is an list of
1670 socket:ioctl_device_flag() | integer().
1671 ioctl(Socket, SetRequest, Name, Value) -> ok | {error, Reason}
1673 Types:
1675 Socket = socket()
1677 SetRequest =
1678 sifflags | sifaddr | sifdstaddr | sifbrdaddr | sifnetmask
1679 |
1680 sifhwaddr | gifmtu | siftxqlen
1681 Name = string()
1682 Value = term()
1683 Reason = posix() | closed
1684 Set socket (device) parameters. This function sets a specific
1686 parameter, according to SetRequest argument. The third argument
1687 is the "key", identifying the interface (usually the name of the
1688 interface), and the fourth is the "new" value.
1689 These are privileged operation's.
1691 sifflags:
1693 Set the the active flag word, #{Flag => boolean()}, of the
1694 interface with the specified name.
1695 Each flag to be changed, should be added to the value map,
1697 with the value 'true' if the flag (Flag) should be set and
1698 'false' if the flag should be reset.
1699 sifaddr:
1701 Set the address, sockaddr(), of the interface with the spec‐
1702 ified name.
1703 sifdstaddr:
1705 Set the destination address, sockaddr(), of a point-to-point
1706 interface with the specified name.
1707 sifbrdaddr:
1709 Set the broadcast address, sockaddr(), of the interface with
1710 the specified name.
1711 sifnetmask:
1713 Set the network mask, sockaddr(), of the interface with the
1714 specified name.
1715 sifmtu:
1717 Set the MTU (Maximum Transfer Unit), integer(), for the in‐
1718 terface with the specified name.
1719 siftxqlen:
1721 Set the transmit queue length, integer(), of the interface
1722 with the specified name.
1723 is_supported(Key1 :: term()) -> boolean()
1725 is_supported(Key1 :: term(), Key2 :: term()) -> boolean()
1727 This function retreives information about what the platform sup‐
1729 ports, such as if SCTP is supported, or if a socket options are
1730 supported.
1731 For keys other than the known false is returned. Note that in a
1733 future version or on a different platform there might be more
1734 supported items.
1735 This functions returns a boolean corresponding to what sup‐
1737 ports/0-2 reports for the same Key1 (and Key2).
1738 listen(Socket) -> ok | {error, Reason}
1740 listen(Socket, Backlog) -> ok | {error, Reason}
1742 Types:
1744 Socket = socket()
1746 Backlog = integer()
1747 Reason = posix() | closed
1748 Listen for connections on a socket.
1750 monitor(Socket) -> reference()
1752 Types:
1754 Socket = socket()
1756 Start monitor the socket Socket.
1758 If the monitored socket does not exist or when the monitor is
1760 triggered, a 'DOWN' message is sent that has the following pat‐
1761 tern:
1762 {'DOWN', MonitorRef, socket, Object, Info}
1764 In the monitor message MonitorRef and Type are the same as de‐
1767 scribed earlier, and:
1768 Object:
1770 The monitored entity, socket, which triggered the event.
1771 Info:
1773 Either the termination reason of the socket or nosock
1774 (socket Socket did not exist at the time of monitor cre‐
1775 ation).
1776 Making several calls to socket:monitor/1 for the same Socket is
1778 not an error; it results in as many independent monitoring in‐
1779 stances.
1780 number_of() -> integer() >= 0
1782 Returns the number of active sockets.
1784 open(FD) -> {ok, Socket} | {error, Reason}
1786 open(FD, Opts) -> {ok, Socket} | {error, Reason}
1788 Types:
1790 FD = integer()
1792 Opts =
1793 #{domain => domain() | integer(),
1794 type => type() | integer(),
1795 protocol => default | protocol() | integer(),
1796 dup => boolean(),
1797 debug => boolean(),
1798 use_registry => boolean()}
1799 Socket = socket()
1800 Reason = posix() | domain | type | protocol
1801 Creates an endpoint (socket) for communication based on an al‐
1803 ready existing file descriptor. The function attempts to re‐
1804 trieve domain, type and protocol from the system. This is how‐
1805 ever not possible on all platforms, and they should then be
1806 specified in Opts.
1807 The Opts argument is intended for providing extra information
1809 for the open call:
1810 domain:
1812 Which protocol domain is the descriptor of. See also
1813 open/2,3,4.
1814 type:
1816 Which protocol type type is the descriptor of.
1817 See also open/2,3,4.
1819 protocol:
1821 Which protocol is the descriptor of. The atom default is
1822 equivalent to the integer protocol number 0 which means the
1823 default protocol for a given domain and type.
1824 If the protocol can not be retrieved from the platform for
1826 the socket, and protocol is not specified, the default pro‐
1827 tocol is used, which may or may not be correct.
1828 See also open/2,3,4.
1830 dup:
1832 Shall the provided descriptor be duplicated (dup) or not.
1833 Defaults to true.
1834 debug:
1836 Enable or disable debug during the open call.
1837 Defaults to false.
1838 use_registry>:
1840 Enable or disable use of the socket registry for this
1841 socket. This overrides the global value.
1842 Defaults to the global value, see use_registry/1.
1843 Note:
1845 This function should be used with care!
1846 On some platforms it is necessary to provide domain, type and
1848 protocol since they cannot be retreived from the platform.
1849 open(Domain, Type) -> {ok, Socket} | {error, Reason}
1852 open(Domain, Type, Opts) -> {ok, Socket} | {error, Reason}
1854 Types:
1856 Domain = domain() | integer()
1858 Type = type() | integer()
1859 Opts = map()
1860 Socket = socket()
1861 Reason = posix() | protocol
1862 Creates an endpoint (socket) for communication.
1864 The same as open(Domain, Type, default) and open(Domain, Type,
1866 default, Opts) respectively.
1867 open(Domain, Type, Protocol) -> {ok, Socket} | {error, Reason}
1869 open(Domain, Type, Protocol, Opts) ->
1871 {ok, Socket} | {error, Reason}
1872 Types:
1874 Domain = domain() | integer()
1876 Type = type() | integer()
1877 Protocol = default | protocol() | integer()
1878 Opts =
1879 #{netns => string(),
1880 debug => boolean(),
1881 use_registry => boolean()}
1882 Socket = socket()
1883 Reason = posix() | protocol
1884 Creates an endpoint (socket) for communication.
1886 Domain and Type may be integer()s, as defined in the platform's
1888 header files. The same goes for Protocol as defined in the plat‐
1889 form's services(5) database. See also the OS man page for the
1890 library call socket(2).
1891 Note:
1893 For some combinations of Domain and Type the platform has got a
1894 default protocol that can be selected with Protocol = default,
1895 and the platform may allow or require selecting the default pro‐
1896 tocol, a specific protocol, or either.
1897 Examples:
1899 socket:open(inet, stream, tcp):
1901 It is common that for protocol domain and type inet,stream
1902 it is allowed to select the tcp protocol although that
1903 mostly is the default.
1904 socket:open(local, dgram):
1906 It is common that for the protocol domain local it is manda‐
1907 tory to not select a protocol, that is; to select the de‐
1908 fault protocol.
1909 The Opts argument is intended for "other" options. The supported
1912 option(s) are described below:
1913 netns: string():
1915 Used to set the network namespace during the open call. Only
1916 supported on the Linux platform.
1917 debug: boolean():
1919 Enable or disable debug during the open call.
1920 Defaults to false.
1921 use_registry: boolean():
1923 Enable or disable use of the socket registry for this
1924 socket. This overrides the global value.
1925 Defaults to the global value, see use_registry/1.
1926 peername(Socket) -> {ok, SockAddr} | {error, Reason}
1928 Types:
1930 Socket = socket()
1932 SockAddr = sockaddr_recv()
1933 Reason = posix() | closed
1934 Returns the address of the peer connected to the socket.
1936 recv(Socket) ->
1938 {ok, Data} | {error, Reason} | {error, {Reason, Data}}
1939 recv(Socket, Flags) ->
1941 {ok, Data} | {error, Reason} | {error, {Reason, Data}}
1942 recv(Socket, Length) ->
1944 {ok, Data} | {error, Reason} | {error, {Reason, Data}}
1945 recv(Socket, Flags, Timeout :: infinity) ->
1947 {ok, Data} | {error, Reason} | {error, {Reason, Data}}
1948 recv(Socket, Length, Flags) ->
1950 {ok, Data} | {error, Reason} | {error, {Reason, Data}}
1951 recv(Socket, Length, Timeout :: infinity) ->
1953 {ok, Data} | {error, Reason} | {error, {Reason, Data}}
1954 recv(Socket, Length, Flags, Timeout :: infinity) ->
1956 {ok, Data} | {error, Reason} | {error, {Reason, Data}}
1957 Types:
1959 Socket = socket()
1961 Length = integer() >= 0
1962 Flags = [msg_flag() | integer()]
1963 Data = binary()
1964 Reason = posix() | closed | invalid()
1965 Receives data from a socket, waiting for it to arrive.
1967 The argument Length specifies how many bytes to receive, with
1969 the special case 0 meaning "all available".
1970 For a socket of type stream this call will not return until all
1972 requested data can be delivered, or if "all available" data was
1973 requested when the first data chunk arrives.
1974 The message Flags may be symbolic msg_flag()s and/or integer()s,
1976 as in the platform's appropriate header files. The values of all
1977 symbolic flags and integers are or:ed together.
1978 When there is a socket error this function returns {error, Rea‐
1980 son}, or if some data arrived before the error; {error, {Reason,
1981 Data}}.
1982 recv(Socket, Flags, Timeout :: integer() >= 0) ->
1984 {ok, Data} | {error, Reason} | {error, {Reason, Data}}
1985 recv(Socket, Length, Timeout :: integer() >= 0) ->
1987 {ok, Data} | {error, Reason} | {error, {Reason, Data}}
1988 recv(Socket, Length, Flags, Timeout :: integer() >= 0) ->
1990 {ok, Data} | {error, Reason} | {error, {Reason, Data}}
1991 Types:
1993 Socket = socket()
1995 Length = integer() >= 0
1996 Flags = [msg_flag() | integer()]
1997 Data = binary()
1998 Reason = posix() | closed | invalid() | timeout
1999 Receives data from a socket, waiting at most Timeout millisec‐
2001 onds for it to arrive.
2002 The same as infinite time-out recv/1,2,3,4 but returns {error,
2004 timeout} or {error, {timeout, Data}} after Timeout milliseconds,
2005 if the requested data has not been delivered.
2006 recv(Socket, Flags, SelectHandle :: nowait) ->
2008 {ok, Data} |
2009 {select, SelectInfo} |
2010 {select, {SelectInfo, Data}} |
2011 {error, Reason} |
2012 {error, {Reason, Data}}
2013 recv(Socket, Flags, SelectHandle :: select_handle()) ->
2015 {ok, Data} |
2016 {select, SelectInfo} |
2017 {select, {SelectInfo, Data}} |
2018 {error, Reason} |
2019 {error, {Reason, Data}}
2020 recv(Socket, Length, SelectHandle :: nowait) ->
2022 {ok, Data} |
2023 {select, SelectInfo} |
2024 {select, {SelectInfo, Data}} |
2025 {error, Reason} |
2026 {error, {Reason, Data}}
2027 recv(Socket, Length, SelectHandle :: select_handle()) ->
2029 {ok, Data} |
2030 {select, SelectInfo} |
2031 {select, {SelectInfo, Data}} |
2032 {error, Reason} |
2033 {error, {Reason, Data}}
2034 recv(Socket, Length, Flags, SelectHandle :: nowait) ->
2036 {ok, Data} |
2037 {select, SelectInfo} |
2038 {select, {SelectInfo, Data}} |
2039 {error, Reason} |
2040 {error, {Reason, Data}}
2041 recv(Socket, Length, Flags, SelectHandle :: select_handle()) ->
2043 {ok, Data} |
2044 {select, SelectInfo} |
2045 {select, {SelectInfo, Data}} |
2046 {error, Reason} |
2047 {error, {Reason, Data}}
2048 Types:
2050 Socket = socket()
2052 Length = integer() >= 0
2053 Flags = [msg_flag() | integer()]
2054 Data = binary()
2055 SelectInfo = select_info()
2056 Reason = posix() | closed | invalid()
2057 Receives data from a socket, but returns a select continuation
2059 if the data could not be returned immediately.
2060 The same as infinite time-out recv/1,2,3,4 but if the data can‐
2062 not be delivered immediately, the function returns {select, Se‐
2063 lectInfo}, and the caller will then receive a select message,
2064 {'$socket', Socket, select, SelectHandle} ( with the Selec‐
2065 tHandle contained in the SelectInfo ) when data has arrived. A
2066 subsequent call to recv/1,2,3,4 will then return the data.
2067 If the time-out argument is SelectHandle, that term will be con‐
2069 tained in a returned SelectInfo and the corresponding select
2070 message. The SelectHandle is presumed to be unique to this call.
2071 If the time-out argument is nowait, and a SelectInfo is re‐
2073 turned, it will contain a select_handle() generated by the call.
2074 Note that for a socket of type stream, if Length > 0 and only
2076 part of that amount of data is available, the function will re‐
2077 turn {ok, {Data, SelectInfo with partial data. If the caller
2078 doesn't want to wait for more data, it must immediately call
2079 cancel/2 to cancel the operation.
2080 recvfrom(Socket) -> {ok, {Source, Data}} | {error, Reason}
2082 recvfrom(Socket, Flags) -> {ok, {Source, Data}} | {error, Reason}
2084 recvfrom(Socket, BufSz) -> {ok, {Source, Data}} | {error, Reason}
2086 recvfrom(Socket, Flags, Timeout :: infinity) ->
2088 {ok, {Source, Data}} | {error, Reason}
2089 recvfrom(Socket, BufSz, Flags) ->
2091 {ok, {Source, Data}} | {error, Reason}
2092 recvfrom(Socket, BufSz, Timeout :: infinity) ->
2094 {ok, {Source, Data}} | {error, Reason}
2095 recvfrom(Socket, BufSz, Flags, Timeout :: infinity) ->
2097 {ok, {Source, Data}} | {error, Reason}
2098 Types:
2100 Socket = socket()
2102 BufSz = integer() >= 0
2103 Flags = [msg_flag() | integer()]
2104 Source = sockaddr_recv()
2105 Data = binary()
2106 Reason = posix() | closed | invalid()
2107 Receive a message from a socket, waiting for it to arrive.
2109 The function returns when a message is received, or when there
2111 is a socket error. Argument BufSz specifies the number of bytes
2112 for the receive buffer. If the buffer size is too small, the
2113 message will be truncated.
2114 If BufSz is not specified or 0, a default buffer size is used,
2116 which can be set by socket:setopt(Socket, {otp,recvbuf}, BufSz).
2117 If it is impossible to know the appropriate buffer size, it may
2119 be possible to use the receive message flag peek. When this flag
2120 is used, the message is not "consumed" from the underlying buf‐
2121 fers, so another recvfrom/1,2,3,4 call is needed, possibly with
2122 an adjusted buffer size.
2123 The message Flags may be symbolic msg_flag()s and/or integer()s,
2125 as in the platform's appropriate header files. The values of all
2126 symbolic flags and integers are or:ed together.
2127 recvfrom(Socket, Flags, Timeout :: integer() >= 0) ->
2129 {ok, {Source, Data}} | {error, Reason}
2130 recvfrom(Socket, BufSz, Timeout :: integer() >= 0) ->
2132 {ok, {Source, Data}} | {error, Reason}
2133 recvfrom(Socket, BufSz, Flags, Timeout :: integer() >= 0) ->
2135 {ok, {Source, Data}} | {error, Reason}
2136 Types:
2138 Socket = socket()
2140 BufSz = integer() >= 0
2141 Flags = [msg_flag() | integer()]
2142 Source = sockaddr_recv()
2143 Data = binary()
2144 Reason = posix() | closed | invalid() | timeout
2145 Receives a message from a socket, waiting at most Timeout mil‐
2147 liseconds for it to arrive.
2148 The same as infinite time-out recvfrom/1,2,3,4 but returns {er‐
2150 ror, timeout} after Timeout milliseconds, if no message has been
2151 delivered.
2152 recvfrom(Socket, Flags, SelectHandle :: nowait) ->
2154 {ok, {Source, Data}} |
2155 {select, SelectInfo} |
2156 {error, Reason}
2157 recvfrom(Socket, Flags, SelectHandle :: select_handle()) ->
2159 {ok, {Source, Data}} |
2160 {select, SelectInfo} |
2161 {error, Reason}
2162 recvfrom(Socket, BufSz, SelectHandle :: nowait) ->
2164 {ok, {Source, Data}} |
2165 {select, SelectInfo} |
2166 {error, Reason}
2167 recvfrom(Socket, BufSz, SelectHandle :: select_handle()) ->
2169 {ok, {Source, Data}} |
2170 {select, SelectInfo} |
2171 {error, Reason}
2172 recvfrom(Socket, BufSz, Flags, SelectHandle :: nowait) ->
2174 {ok, {Source, Data}} |
2175 {select, SelectInfo} |
2176 {error, Reason}
2177 recvfrom(Socket, BufSz, Flags, SelectHandle :: select_handle()) ->
2179 {ok, {Source, Data}} |
2180 {select, SelectInfo} |
2181 {error, Reason}
2182 Types:
2184 Socket = socket()
2186 BufSz = integer() >= 0
2187 Flags = [msg_flag() | integer()]
2188 Source = sockaddr_recv()
2189 Data = binary()
2190 SelectInfo = select_info()
2191 Reason = posix() | closed | invalid()
2192 Receives a message from a socket, but returns a select continua‐
2194 tion if no message could be returned immediately.
2195 The same as infinite time-out recvfrom/1,2,3,4 but if no mes‐
2197 sage cannot delivered immediately, the function returns {select,
2198 SelectInfo}, and the caller will then receive a select message,
2199 {'$socket', Socket, select, SelectHandle} ( with the Selec‐
2200 tHandle contained in the SelectInfo ) when data has arrived. A
2201 subsequent call to recvfrom/1,2,3,4 will then return the mes‐
2202 sage.
2203 If the time-out argument is SelectHandle, that term will be con‐
2205 tained in a returned SelectInfo and the corresponding select
2206 message. The SelectHandle is presumed to be unique to this call.
2207 If the time-out argument is nowait, and a SelectInfo is re‐
2209 turned, it will contain a select_handle() generated by the call.
2210 If the caller doesn't want to wait for the data, it must immedi‐
2212 ately call cancel/2 to cancel the operation.
2213 recvmsg(Socket) -> {ok, Msg} | {error, Reason}
2215 recvmsg(Socket, Flags) -> {ok, Msg} | {error, Reason}
2217 recvmsg(Socket, Timeout :: infinity) ->
2219 {ok, Msg} | {error, Reason}
2220 recvmsg(Socket, Flags, Timeout :: infinity) ->
2222 {ok, Msg} | {error, Reason}
2223 recvmsg(Socket, BufSz, CtrlSz) -> {ok, Msg} | {error, Reason}
2225 recvmsg(Socket, BufSz, CtrlSz, Timeout :: infinity) ->
2227 {ok, Msg} | {error, Reason}
2228 recvmsg(Socket, BufSz, CtrlSz, Flags, Timeout :: infinity) ->
2230 {ok, Msg} | {error, Reason}
2231 Types:
2233 Socket = socket()
2235 BufSz = CtrlSz = integer() >= 0
2236 Flags = [msg_flag() | integer()]
2237 Msg = msg_recv()
2238 Reason = posix() | closed | invalid()
2239 Receive a message from a socket, waiting for it to arrive.
2241 The function returns when a message is received, or when there
2243 is a socket error. Arguments BufSz and CtrlSz specifies the num‐
2244 ber of bytes for the receive buffer and the control message buf‐
2245 fer. If the buffer size(s) is(are) too small, the message and/or
2246 control message list will be truncated.
2247 If BufSz is not specified or 0, a default buffer size is used,
2249 which can be set by socket:setopt(Socket, {otp,recvbuf}, BufSz).
2250 The same applies to CtrlSz and socket:setopt(Socket, {otp,recvc‐
2251 trlbuf}, CtrlSz).
2252 If it is impossible to know the appropriate buffer size, it may
2254 be possible to use the receive message flag peek. When this flag
2255 is used, the message is not "consumed" from the underlying buf‐
2256 fers, so another recvfrom/1,2,3,4,5 call is needed, possibly
2257 with an adjusted buffer size.
2258 The message Flags may be symbolic msg_flag()s and/or integer()s,
2260 as in the platform's appropriate header files. The values of all
2261 symbolic flags and integers are or:ed together.
2262 recvmsg(Socket, Timeout :: integer() >= 0) ->
2264 {ok, Msg} | {error, Reason}
2265 recvmsg(Socket, Flags, Timeout :: integer() >= 0) ->
2267 {ok, Msg} | {error, Reason}
2268 recvmsg(Socket, BufSz, CtrlSz, Timeout :: integer() >= 0) ->
2270 {ok, Msg} | {error, Reason}
2271 recvmsg(Socket, BufSz, CtrlSz, Flags,
2273 Timeout :: integer() >= 0) ->
2274 {ok, Msg} | {error, Reason}
2275 Types:
2277 Socket = socket()
2279 BufSz = CtrlSz = integer() >= 0
2280 Flags = [msg_flag() | integer()]
2281 Msg = msg_recv()
2282 Reason = posix() | closed | invalid() | timeout
2283 Receives a message from a socket, waiting at most Timeout mil‐
2285 liseconds for it to arrive.
2286 The same as recvmsg/1,2,3,4,5 but returns {error, timeout} after
2288 Timeout milliseconds, if no message has been delivered.
2289 recvmsg(Socket, Timeout :: nowait) ->
2291 {ok, Msg} | {select, SelectInfo} | {error, Reason}
2292 recvmsg(Socket, SelectHandle :: select_handle()) ->
2294 {ok, Msg} | {select, SelectInfo} | {error, Reason}
2295 recvmsg(Socket, Flags, Timeout :: nowait) ->
2297 {ok, Msg} | {select, SelectInfo} | {error, Reason}
2298 recvmsg(Socket, Flags, SelectHandle :: select_handle()) ->
2300 {ok, Msg} | {select, SelectInfo} | {error, Reason}
2301 recvmsg(Socket, BufSz, CtrlSz, SelectHandle :: nowait) ->
2303 {ok, Msg} | {select, SelectInfo} | {error, Reason}
2304 recvmsg(Socket, BufSz, CtrlSz, SelectHandle :: select_handle()) ->
2306 {ok, Msg} | {select, SelectInfo} | {error, Reason}
2307 recvmsg(Socket, BufSz, CtrlSz, Flags, SelectHandle :: nowait) ->
2309 {ok, Msg} | {select, SelectInfo} | {error, Reason}
2310 recvmsg(Socket, BufSz, CtrlSz, Flags,
2312 SelectHandle :: select_handle()) ->
2313 {ok, Msg} | {select, SelectInfo} | {error, Reason}
2314 Types:
2316 Socket = socket()
2318 BufSz = CtrlSz = integer() >= 0
2319 Flags = [msg_flag() | integer()]
2320 Msg = msg_recv()
2321 SelectInfo = select_info()
2322 Reason = posix() | closed | invalid()
2323 Receives a message from a socket, but returns a select continua‐
2325 tion if no message could be returned immediately.
2326 The same as infinite time-out recvfrom/1,2,3,4 but if no mes‐
2328 sage cannot delivered immediately, the function returns {select,
2329 SelectInfo}, and the caller will then receive a select message,
2330 {'$socket', Socket, select, SelectHandle} ( with the Selec‐
2331 tHandle contained in the SelectInfo ) when data has arrived. A
2332 subsequent call to recvmsg/1,2,3,4,5 will then return the data.
2333 If the time-out argument is SelectHandle, that term will be con‐
2335 tained in a returned SelectInfo and the corresponding select
2336 message. The SelectHandle is presumed to be unique to this call.
2337 If the time-out argument is nowait, and a SelectInfo is re‐
2339 turned, it will contain a select_handle() generated by the call.
2340 If the caller doesn't want to wait for the data, it must immedi‐
2342 ately call cancel/2 to cancel the operation.
2343 send(Socket, Data) ->
2345 ok |
2346 {ok, RestData} |
2347 {error, Reason} |
2348 {error, {Reason, RestData}}
2349 send(Socket, Data, Flags) ->
2351 ok |
2352 {ok, RestData} |
2353 {error, Reason} |
2354 {error, {Reason, RestData}}
2355 send(Socket, Data, Timeout :: infinity) ->
2357 ok |
2358 {ok, RestData} |
2359 {error, Reason} |
2360 {error, {Reason, RestData}}
2361 send(Socket, Data, Flags, Timeout :: infinity) ->
2363 ok |
2364 {ok, RestData} |
2365 {error, Reason} |
2366 {error, {Reason, RestData}}
2367 Types:
2369 Socket = socket()
2371 Data = iodata()
2372 Flags = [msg_flag() | integer()]
2373 RestData = binary()
2374 Reason = posix() | closed | invalid()
2375 Sends data on a connected socket, waiting for it to be sent.
2377 This call will not return until the Data has been accepted by
2379 the platform's network layer, or it reports an error.
2380 The message Flags may be symbolic msg_flag()s and/or integer()s,
2382 matching the platform's appropriate header files. The values of
2383 all symbolic flags and integers are or:ed together.
2384 The Data, if it is not a binary(), is copied into one before
2386 calling the platform network API, because a single buffer is re‐
2387 quired. A returned RestData is a sub binary of this data binary.
2388 The return value indicates the result from the platform's net‐
2390 work layer:
2391 ok:
2393 All data has been accepted.
2394 {ok, RestData}:
2396 Not all data has been accepted, but no error has been re‐
2397 ported. RestData is the tail of Data that has not been ac‐
2398 cepted.
2399 This cannot happen for a socket of type stream where a par‐
2401 tially succesful send is retried until the data is either
2402 accepted or there is an error.
2403 For a socket of type dgram this should probably also not
2405 happen since a message that cannot be passed atomically
2406 should render an error.
2407 It is nevertheless possible for the platform's network layer
2409 to return this.
2410 {error, Reason}:
2412 An error has been reported and no data has been accepted.
2413 The posix() Reasons are from the platform's network layer.
2414 closed means that this socket library knows that the socket
2415 is closed, and invalid() means that something about an argu‐
2416 ment is invalid.
2417 {error, {Reason, RestData}} :
2419 An error has been reported but before that some data was ac‐
2420 cepted. RestData is the tail of Data that has not been ac‐
2421 cepted. See {error, Reason} above.
2422 This can only happen for a socket of type stream when a par‐
2424 tially succesful send is retried untill there is an error.
2425 send(Socket, Data, Timeout :: integer() >= 0) ->
2427 ok |
2428 {ok, RestData} |
2429 {error, Reason | timeout} |
2430 {error, {Reason | timeout, RestData}}
2431 send(Socket, Data, Flags, Timeout :: integer() >= 0) ->
2433 ok |
2434 {ok, RestData} |
2435 {error, Reason | timeout} |
2436 {error, {Reason | timeout, RestData}}
2437 Types:
2439 Socket = socket()
2441 Data = iodata()
2442 Flags = [msg_flag() | integer()]
2443 RestData = binary()
2444 Reason = posix() | closed | invalid()
2445 Sends data on a connected socket, waiting at most Timeout mil‐
2447 liseconds for it to be sent.
2448 The same as infinite time-out send/2,3,4 but returns {error,
2450 timeout} or {error, {timeout, RestData}} after Timeout millisec‐
2451 onds, if no Data or only some of it was accepted by the plat‐
2452 form's network layer.
2453 send(Socket, Data, SelectHandle :: nowait) ->
2455 ok |
2456 {ok, RestData} |
2457 {select, SelectInfo} |
2458 {select, {SelectInfo, RestData}} |
2459 {error, Reason}
2460 send(Socket, Data, SelectHandle :: select_handle()) ->
2462 ok |
2463 {ok, RestData} |
2464 {select, SelectInfo} |
2465 {select, {SelectInfo, RestData}} |
2466 {error, Reason}
2467 send(Socket, Data, Flags, SelectHandle :: nowait) ->
2469 ok |
2470 {ok, RestData} |
2471 {select, SelectInfo} |
2472 {select, {SelectInfo, RestData}} |
2473 {error, Reason}
2474 send(Socket, Data, Flags, SelectHandle :: select_handle()) ->
2476 ok |
2477 {ok, RestData} |
2478 {select, SelectInfo} |
2479 {select, {SelectInfo, RestData}} |
2480 {error, Reason}
2481 Types:
2483 Socket = socket()
2485 Data = iodata()
2486 Flags = [msg_flag() | integer()]
2487 RestData = binary()
2488 SelectInfo = select_info()
2489 Reason = posix() | closed | invalid()
2490 Sends data on a connected socket, but returns a select continua‐
2492 tion if the data could not be sent immediately.
2493 The same as infinite time-out send/2,3 but if the data is not
2495 immediately accepted by the platform network layer, the function
2496 returns {select, SelectInfo}, and the caller will then receive a
2497 select message, {'$socket', Socket, select, SelectHandle} ( with
2498 the SelectHandle that was contained in the SelectInfo ) when
2499 there is room for more data. A subsequent call to send/2-4 will
2500 then send the data.
2501 If SelectHandle is a select_handle(), that term will be con‐
2503 tained in a returned SelectInfo and the corresponding select
2504 message. The SelectHandle is presumed to be unique to this call.
2505 If SelectHandle is nowait, and a SelectInfo is returned, it will
2507 contain a select_handle() generated by the call.
2508 If some of the data was sent, the function will return {ok,
2510 {RestData, SelectInfo}, which can only happen for a socket of
2511 type stream. If the caller does not want to wait to send the
2512 rest of the data, it should immediately cancel the operation
2513 with cancel/2.
2514 send(Socket, Data, Cont) ->
2516 ok |
2517 {ok, RestData} |
2518 {error, Reason} |
2519 {error, {Reason, RestData}}
2520 send(Socket, Data, Cont, Timeout :: infinity) ->
2522 ok |
2523 {ok, RestData} |
2524 {error, Reason} |
2525 {error, {Reason, RestData}}
2526 send(Socket, Data, Cont, Timeout :: integer() >= 0) ->
2528 ok |
2529 {ok, RestData} |
2530 {error, Reason | timeout} |
2531 {error, {Reason | timeout, RestData}}
2532 send(Socket, Data, Cont, SelectHandle :: nowait) ->
2534 ok |
2535 {ok, RestData} |
2536 {select, SelectInfo} |
2537 {select, {SelectInfo, RestData}} |
2538 {error, Reason}
2539 send(Socket, Data, Cont, SelectHandle :: select_handle()) ->
2541 ok |
2542 {ok, RestData} |
2543 {select, SelectInfo} |
2544 {select, {SelectInfo, RestData}} |
2545 {error, Reason}
2546 Types:
2548 Socket = socket()
2550 Data = iodata()
2551 Cont = select_info()
2552 RestData = binary()
2553 SelectInfo = select_info()
2554 Reason = posix() | closed | invalid()
2555 Continues sending data on a connected socket, where the send op‐
2557 eration was initiated by send/3,4 that returned a SelectInfo
2558 continuation. Otherwise like infinite time-out send/2,3,4 ,
2559 limited time-out send/3,4 or nowait send/3,4 respectively.
2560 Cont is the SelectInfo that was returned from the previous
2562 send() call.
2563 If Data is not a binary(), it will be copied into one, again.
2565 The return value indicates the result from the platform's net‐
2567 work layer. See send/2,3,4 and nowait send/3,4.
2568 sendmsg(Socket, Msg) ->
2570 ok |
2571 {ok, RestData} |
2572 {error, Reason} |
2573 {error, {Reason, RestData}}
2574 sendmsg(Socket, Msg, Flags) ->
2576 ok |
2577 {ok, RestData} |
2578 {error, Reason} |
2579 {error, {Reason, RestData}}
2580 sendmsg(Socket, Msg, Timeout :: infinity) ->
2582 ok |
2583 {ok, RestData} |
2584 {error, Reason} |
2585 {error, {Reason, RestData}}
2586 sendmsg(Socket, Msg, Flags, Timeout :: infinity) ->
2588 ok |
2589 {ok, RestData} |
2590 {error, Reason} |
2591 {error, {Reason, RestData}}
2592 Types:
2594 Socket = socket()
2596 Msg = msg_send()
2597 Flags = [msg_flag() | integer()]
2598 RestData = erlang:iovec()
2599 Reason = posix() | closed | invalid()
2600 Sends a message on a socket, waiting for it to be sent.
2602 The destination, if needed, that is: if the socket is not con‐
2604 nected, is provided in Msg, which also contains the data to send
2605 as a list of binaries. Msg may also contain an list of optional
2606 control messages (depending on what the protocol and platform
2607 supports).
2608 For a connected socket no address field should be present in
2610 Msg, the platform may return an error or ignore one.
2611 The message data is given to to the platform's network layer in
2613 the form of an I/O vector without copying the content. If the
2614 number of elements in the I/O vector is larger than allowed on
2615 the platform (reported in the iov_max field from info/0), on a
2616 socket of type stream the send is iterated over all elements,
2617 but for other socket types the call fails.
2618 This call will not return until the data has been handed over to
2620 the platform's network layer, or when it reports an error.
2621 The message Flags may be symbolic msg_flag()s and/or integer()s,
2623 matching the platform's appropriate header files. The values of
2624 all symbolic flags and integers are or:ed together.
2625 The return value indicates the result from the platform's net‐
2627 work layer. See send/2,3,4.
2628 sendmsg(Socket, Msg, Timeout :: integer() >= 0) ->
2630 ok |
2631 {ok, RestData} |
2632 {error, Reason | timeout} |
2633 {error, {Reason | timeout, RestData}}
2634 sendmsg(Socket, Msg, Flags, Timeout :: integer() >= 0) ->
2636 ok |
2637 {ok, RestData} |
2638 {error, Reason | timeout} |
2639 {error, {Reason | timeout, RestData}}
2640 Types:
2642 Socket = socket()
2644 Msg = msg_send()
2645 Flags = [msg_flag() | integer()]
2646 RestData = erlang:iovec()
2647 Reason = posix() | closed | invalid()
2648 Sends a message on a socket, waiting at most Timeout millisec‐
2650 onds for it to be sent.
2651 The same as infinite time-out sendmsg/2,3,4 but returns {error,
2653 timeout} or {error, {timeout, RestData}} after Timeout millisec‐
2654 onds, if no data or only some of it was accepted by the plat‐
2655 form's network layer.
2656 sendmsg(Socket, Msg, Timeout :: nowait) ->
2658 ok |
2659 {ok, RestData} |
2660 {select, SelectInfo} |
2661 {select, {SelectInfo, RestData}} |
2662 {error, Reason} |
2663 {error, {Reason, RestData}}
2664 sendmsg(Socket, Msg, SelectHandle :: select_handle()) ->
2666 ok |
2667 {ok, RestData} |
2668 {select, SelectInfo} |
2669 {select, {SelectInfo, RestData}} |
2670 {error, Reason} |
2671 {error, {Reason, RestData}}
2672 sendmsg(Socket, Msg, Flags, SelectHandle :: nowait) ->
2674 ok |
2675 {ok, RestData} |
2676 {select, SelectInfo} |
2677 {select, {SelectInfo, RestData}} |
2678 {error, Reason} |
2679 {error, {Reason, RestData}}
2680 sendmsg(Socket, Msg, Flags, SelectHandle :: select_handle()) ->
2682 ok |
2683 {ok, RestData} |
2684 {select, SelectInfo} |
2685 {select, {SelectInfo, RestData}} |
2686 {error, Reason} |
2687 {error, {Reason, RestData}}
2688 Types:
2690 Socket = socket()
2692 Msg = msg_send()
2693 Flags = [msg_flag() | integer()]
2694 RestData = erlang:iovec()
2695 SelectInfo = select_info()
2696 Reason = posix() | closed | invalid()
2697 Sends a message on a socket, but returns a select continuation
2699 if the data could not be sent immediately.
2700 The same as infinity time-out sendmsg/2,3 but if the data is
2702 not immediately accepted by the platform network layer, the
2703 function returns {select, SelectInfo}, and the caller will then
2704 receive a select message, {'$socket', Socket, select, Selec‐
2705 tHandle} ( with the SelectHandle that was contained in the Se‐
2706 lectInfo ) when there is room for more data. A subsequent call
2707 to sendmsg/2-4 will then send the data.
2708 If SelectHandle, is a select_handle(), that term will be con‐
2710 tained in a returned SelectInfo and the corresponding select
2711 message. The SelectHandle is presumed to be unique to this call.
2712 If SelectHandle is nowait, and a SelectInfo is returned, it will
2714 contain a select_handle() generated by the call.
2715 If some of the data was sent, the function will return {ok,
2717 {RestData, SelectInfo}, which can only happen for a socket of
2718 type stream. If the caller does not want to wait to send the
2719 rest of the data, it should immediately cancel the operation
2720 with cancel/2.
2721 sendmsg(Socket, Data, Cont) ->
2723 ok |
2724 {ok, RestData} |
2725 {error, Reason} |
2726 {error, {Reason, RestData}}
2727 sendmsg(Socket, Data, Cont, Timeout :: infinity) ->
2729 ok |
2730 {ok, RestData} |
2731 {error, Reason} |
2732 {error, {Reason, RestData}}
2733 sendmsg(Socket, Data, Cont, Timeout :: integer() >= 0) ->
2735 ok |
2736 {ok, RestData} |
2737 {error, Reason | timeout} |
2738 {error, {Reason | timeout, RestData}}
2739 sendmsg(Socket, Data, Cont, SelectHandle :: nowait) ->
2741 ok |
2742 {ok, RestData} |
2743 {select, SelectInfo} |
2744 {select, {SelectInfo, RestData}} |
2745 {error, Reason} |
2746 {error, {Reason, RestData}}
2747 sendmsg(Socket, Data, Cont, SelectHandle :: select_handle()) ->
2749 ok |
2750 {ok, RestData} |
2751 {select, SelectInfo} |
2752 {select, {SelectInfo, RestData}} |
2753 {error, Reason} |
2754 {error, {Reason, RestData}}
2755 Types:
2757 Socket = socket()
2759 Data = msg_send() | erlang:iovec()
2760 Cont = select_info()
2761 RestData = erlang:iovec()
2762 SelectInfo = select_info()
2763 Reason = posix() | closed | invalid()
2764 Continues sending a message data on a socket, where the send op‐
2766 eration was initiated by sendmsg/3,4 that returned a SelectInfo
2767 continuation. Otherwise like infinite time-out sendmsg/2,3,4 ,
2768 limited time-out sendmsg/3,4 or nowait sendmsg/3,4 respec‐
2769 tively.
2770 Cont is the SelectInfo that was returned from the previous
2772 sendmsg() call.
2773 The return value indicates the result from the platform's net‐
2775 work layer. See send/2,3,4 and nowait sendmsg/3,4.
2776 sendto(Socket, Data, Dest) ->
2778 ok |
2779 {ok, RestData} |
2780 {error, Reason} |
2781 {error, {Reason, RestData}}
2782 sendto(Socket, Data, Dest, Flags) ->
2784 ok |
2785 {ok, RestData} |
2786 {error, Reason} |
2787 {error, {Reason, RestData}}
2788 sendto(Socket, Data, Dest, Timeout :: infinity) ->
2790 ok |
2791 {ok, RestData} |
2792 {error, Reason} |
2793 {error, {Reason, RestData}}
2794 sendto(Socket, Data, Dest, Flags, Timeout :: infinity) ->
2796 ok |
2797 {ok, RestData} |
2798 {error, Reason} |
2799 {error, {Reason, RestData}}
2800 Types:
2802 Socket = socket()
2804 Data = iodata()
2805 Dest = sockaddr()
2806 Flags = [msg_flag() | integer()]
2807 RestData = binary()
2808 Reason = posix() | closed | invalid()
2809 Sends data on a socket, to the specified destination, waiting
2811 for it to be sent.
2812 This call will not return until the data has been accepted by
2814 the platform's network layer, or it reports an error.
2815 If this call is used on a connection mode socket or on a con‐
2817 nected socket, the platforms's network layer may return an error
2818 or ignore the destination address.
2819 The message Flags may be symbolic msg_flag()s and/or integer()s,
2821 matching the platform's appropriate header files. The values of
2822 all symbolic flags and integers are or:ed together.
2823 The return value indicates the result from the platform's net‐
2825 work layer. See send/2,3,4.
2826 sendto(Socket, Data, Dest, Timeout :: integer() >= 0) ->
2828 ok |
2829 {ok, RestData} |
2830 {error, Reason | timeout} |
2831 {error, {Reason | timeout, RestData}}
2832 sendto(Socket, Data, Dest, Flags, Timeout :: integer() >= 0) ->
2834 ok |
2835 {ok, RestData} |
2836 {error, Reason | timeout} |
2837 {error, {Reason | timeout, RestData}}
2838 Types:
2840 Socket = socket()
2842 Data = iodata()
2843 Dest = sockaddr()
2844 Flags = [msg_flag() | integer()]
2845 RestData = binary()
2846 Reason = posix() | closed | invalid()
2847 Sends data on a socket, waiting at most Timeout milliseconds for
2849 it to be sent.
2850 The same as infinite time-out sendto/3,4,5 but returns {error,
2852 timeout} or {error, {timeout, RestData}} after Timeout millisec‐
2853 onds, if no Data or only some of it was accepted by the plat‐
2854 form's network layer.
2855 sendto(Socket, Data, Dest, SelectHandle :: nowait) ->
2857 ok |
2858 {ok, RestData} |
2859 {select, SelectInfo} |
2860 {select, {SelectInfo, RestData}} |
2861 {error, Reason}
2862 sendto(Socket, Data, Dest, SelectHandle :: select_handle()) ->
2864 ok |
2865 {ok, RestData} |
2866 {select, SelectInfo} |
2867 {select, {SelectInfo, RestData}} |
2868 {error, Reason}
2869 sendto(Socket, Data, Dest, Flags, SelectHandle :: nowait) ->
2871 ok |
2872 {ok, RestData} |
2873 {select, SelectInfo} |
2874 {select, {SelectInfo, RestData}} |
2875 {error, Reason}
2876 sendto(Socket, Data, Dest, Flags, SelectHandle :: select_handle()) ->
2878 ok |
2879 {ok, RestData} |
2880 {select, SelectInfo} |
2881 {select, {SelectInfo, RestData}} |
2882 {error, Reason}
2883 Types:
2885 Socket = socket()
2887 Data = iodata()
2888 Dest = sockaddr()
2889 Flags = [msg_flag() | integer()]
2890 RestData = binary()
2891 SelectInfo = select_info()
2892 Reason = posix() | closed | invalid()
2893 Sends data on a socket, but returns a select continuation if the
2895 data could not be sent immediately.
2896 The same as infinity time-out sendto/3,4 but if the data is not
2898 immediately accepted by the platform network layer, the function
2899 returns {select, SelectInfo}, and the caller will then receive a
2900 select message, {'$socket', Socket, select, SelectHandle} ( with
2901 the SelectHandle that was contained in the SelectInfo ) when
2902 there is room for more data. A subsequent call to sendto/3-5
2903 will then send the data.
2904 If SelectHandle is a select_handle(), that term will be con‐
2906 tained in a returned SelectInfo and the corresponding select
2907 message. The SelectHandle is presumed to be unique to this call.
2908 If SelectHandle is nowait, and a SelectInfo is returned, it will
2910 contain a select_handle() generated by the call.
2911 If some of the data was sent, the function will return {ok,
2913 {RestData, SelectInfo}, which can only happen for a socket of
2914 type stream. If the caller does not want to wait to send the
2915 rest of the data, it should immediately cancel the operation
2916 with cancel/2.
2917 sendto(Socket, Data, Cont) ->
2919 ok |
2920 {ok, RestData} |
2921 {error, Reason} |
2922 {error, {Reason, RestData}}
2923 sendto(Socket, Data, Cont, Timeout :: infinity) ->
2925 ok |
2926 {ok, RestData} |
2927 {error, Reason} |
2928 {error, {Reason, RestData}}
2929 sendto(Socket, Data, Cont, Timeout :: integer() >= 0) ->
2931 ok |
2932 {ok, RestData} |
2933 {error, Reason | timeout} |
2934 {error, {Reason | timeout, RestData}}
2935 sendto(Socket, Data, Cont, SelectHandle :: nowait) ->
2937 ok |
2938 {ok, RestData} |
2939 {select, SelectInfo} |
2940 {select, {SelectInfo, RestData}} |
2941 {error, Reason}
2942 sendto(Socket, Data, Cont, SelectHandle :: select_handle()) ->
2944 ok |
2945 {ok, RestData} |
2946 {select, SelectInfo} |
2947 {select, {SelectInfo, RestData}} |
2948 {error, Reason}
2949 Types:
2951 Socket = socket()
2953 Data = iodata()
2954 Cont = select_info()
2955 RestData = binary()
2956 SelectInfo = select_info()
2957 Reason = posix() | closed | invalid()
2958 Continues sending data on a socket, where the send operation was
2960 initiated by sendto/4,5 that returned a SelectInfo continuation.
2961 Otherwise like infinite time-out sendto/3,4,5 , limited time-
2962 out sendto/4,5 or nowait sendto/4,5 respectively.
2963 Cont is the SelectInfo that was returned from the previous
2965 sendto() call.
2966 If Data is not a binary(), it will be copied into one, again.
2968 The return value indicates the result from the platform's net‐
2970 work layer. See send/2,3,4 and nowait sendto/4,5.
2971 sendfile(Socket, FileHandle, Offset, Count, Timeout :: infinity) ->
2973 {ok, BytesSent} |
2974 {error, Reason} |
2975 {error, {Reason, BytesSent}}
2976 Types:
2978 Socket = socket()
2980 FileHandle = file:fd()
2981 Offset = integer()
2982 Count = BytesSent = integer() >= 0
2983 Reason = posix() | closed | invalid()
2984 Sends file data on a socket, to the specified destination, wait‐
2986 ing for it to be sent ("infinite" time-out).
2987 The FileHandle must refer to an open raw file as described in
2989 file:open/2.
2990 This call will not return until the data has been accepted by
2992 the platform's network layer, or it reports an error.
2993 The Offset argument is the file offset to start reading from.
2995 The default value is 0.
2996 The Count argument is the number of bytes to transfer from File‐
2998 Handle to Socket. If Count =:= 0 (the default) the transfer
2999 stops at the end of file.
3000 The return value indicates the result from the platform's net‐
3002 work layer:
3003 {ok, BytesSent}:
3005 The transfer completed succesfully after BytesSent bytes of
3006 data.
3007 {error, Reason}:
3009 An error has been reported and no data has been transferred.
3010 The posix() Reasons are from the platform's network layer.
3011 closed means that this socket library knows that the socket
3012 is closed, and invalid() means that something about an argu‐
3013 ment is invalid.
3014 {error, {Reason, BytesSent}} :
3016 An error has been reported but before that some data was
3017 transferred. See {error, Reason} and {ok, BytesSent} above.
3018 sendfile(Socket, FileHandle, Offset, Count,
3020 Timeout :: integer() >= 0) ->
3021 {ok, BytesSent} |
3022 {error, Reason | timeout} |
3023 {error, {Reason | timeout, BytesSent}}
3024 Types:
3026 Socket = socket()
3028 FileHandle = file:fd()
3029 Offset = integer()
3030 Count = BytesSent = integer() >= 0
3031 Reason = posix() | closed | invalid()
3032 Sends file data on a socket, waiting at most Timeout millisec‐
3034 onds for it to be sent (limited time-out).
3035 The same as "infinite" time-out sendfile/5 but returns {error,
3037 timeout} or {error, {timeout, BytesSent}} after Timeout mil‐
3038 liseconds, if not all file data was transferred by the plat‐
3039 form's network layer.
3040 sendfile(Socket, FileHandle, Offset, Count,
3042 SelectHandle :: nowait) ->
3043 {ok, BytesSent} |
3044 {select, SelectInfo} |
3045 {select, {SelectInfo, BytesSent}} |
3046 {error, Reason}
3047 sendfile(Socket, FileHandle, Offset, Count,
3049 SelectHandle :: select_handle()) ->
3050 {ok, BytesSent} |
3051 {select, SelectInfo} |
3052 {select, {SelectInfo, BytesSent}} |
3053 {error, Reason}
3054 Types:
3056 Socket = socket()
3058 FileHandle = file:fd()
3059 Offset = integer()
3060 Count = BytesSent = integer() >= 0
3061 SelectInfo = select_info()
3062 Reason = posix() | closed | invalid()
3063 Sends file data on a socket, but returns a select continuation
3065 if the data could not be sent immediately (nowait).
3066 The same as "infinite" time-out sendfile/5 but if the data is
3068 not immediately accepted by the platform network layer, the
3069 function returns {select, SelectInfo}, and the caller will then
3070 receive a select message, {'$socket', Socket, select, Selec‐
3071 tHandle} ( with the SelectHandle that was contained in the Se‐
3072 lectInfo ) when there is room for more data. Then a call to
3073 sendfile/3 with SelectInfo as the second argument will continue
3074 the data transfer.
3075 If SelectHandle is a select_handle(), that term will be con‐
3077 tained in a returned SelectInfo and the corresponding select
3078 message. The SelectHandle is presumed to be unique to this call.
3079 If SelectHandle is nowait, and a SelectInfo is returned, it will
3081 contain a select_handle() generated by the call.
3082 If some file data was sent, the function will return {ok,
3084 {BytesSent, SelectInfo}. If the caller does not want to wait to
3085 send the rest of the data, it should immediately cancel the op‐
3086 eration with cancel/2.
3087 sendfile(Socket, Cont, Offset, Count, Timeout :: infinity) ->
3089 {ok, BytesSent} |
3090 {error, Reason} |
3091 {error, {Reason, BytesSent}}
3092 sendfile(Socket, Cont, Offset, Count,
3094 Timeout :: integer() >= 0) ->
3095 {ok, BytesSent} |
3096 {error, Reason | timeout} |
3097 {error, {Reason | timeout, BytesSent}}
3098 sendfile(Socket, Cont, Offset, Count, SelectHandle :: nowait) ->
3100 {ok, BytesSent} |
3101 {select, SelectInfo} |
3102 {select, {SelectInfo, BytesSent}} |
3103 {error, Reason}
3104 sendfile(Socket, Cont, Offset, Count,
3106 SelectHandle :: select_handle()) ->
3107 {ok, BytesSent} |
3108 {select, SelectInfo} |
3109 {select, {SelectInfo, BytesSent}} |
3110 {error, Reason}
3111 Types:
3113 Socket = socket()
3115 Cont = select_info()
3116 Offset = integer()
3117 Count = BytesSent = integer() >= 0
3118 SelectInfo = select_info()
3119 Reason = posix() | closed | invalid()
3120 Continues sending file data on a socket, where the send opera‐
3122 tion was initiated by sendfile/3,5 that returned a SelectInfo
3123 continuation. Otherwise like "infinite" time-out sendfile/5 ,
3124 limited time-out sendfile/5 or nowait sendfile/5 respectively.
3125 Cont is the SelectInfo that was returned from the previous send‐
3127 file() call.
3128 The return value indicates the result from the platform's net‐
3130 work layer. See "infinite" time-out sendfile/5.
3131 sendfile(Socket, FileHandle, Offset, Count) -> Result
3133 Types:
3135 Socket = socket()
3137 FileHandle = file:fd()
3138 Offset = integer()
3139 Count = integer() >= 0
3140 The same as sendfile(Socket, FileHandle, Offset, Count, infin‐
3142 ity), that is: send the file data at Offset and Count to the
3143 socket, without time-out other than from the platform's network
3144 stack.
3145 sendfile(Socket, FileHandle, Timeout) -> Result
3147 Types:
3149 Socket = socket()
3151 FileHandle = file:fd()
3152 Timeout = timeout() | 'nowait' | select_handle()
3153 Depending on the Timeout argument; the same as sendfile(Socket,
3155 FileHandle, 0, 0, infinity), sendfile(Socket, FileHandle, 0,
3156 0, Timeout), or sendfile(Socket, FileHandle, 0, 0, Selec‐
3157 tHandle), that is: send all data in the file to the socket,
3158 with the given Timeout.
3159 sendfile(Socket, FileHandle) -> Result
3161 Types:
3163 Socket = socket()
3165 FileHandle = file:fd()
3166 The same as sendfile(Socket, FileHandle, 0, 0, infinity), that
3168 is: send all data in the file to the socket, without time-out
3169 other than from the platform's network stack.
3170 setopt(Socket :: socket(),
3172 SocketOption :: {Level :: otp, Opt :: otp_socket_option()},
3173 Value :: term()) ->
3174 ok | {error, invalid() | closed}
3175 Sets a socket option in the protocol level otp, which is this
3177 implementation's level above the OS protocol layers.
3178 See the type otp_socket_option() for a description of the op‐
3180 tions on this level.
3181 setopt(Socket :: socket(),
3183 SocketOption :: socket_option(),
3184 Value :: term()) ->
3185 ok | {error, posix() | invalid() | closed}
3186 Set a socket option in one of the OS's protocol levels. See the
3188 type socket_option() for which options that this implementation
3189 knows about, how they are related to option names in the OS, and
3190 if there are known pecularities with any of them.
3191 What options are valid depends on what kind of socket it is (do‐
3193 main(), type() and protocol()).
3194 See the socket options chapter of the users guide for more
3196 info.
3197 Note:
3199 Not all options are valid, nor possible to set, on all plat‐
3200 forms. That is, even if "we" support an option; it does not mean
3201 that the underlying OS does.
3202 setopt(Socket, Level, Opt, Value) -> ok | {error, Reason}
3205 Types:
3207 Socket = socket()
3209 Value = term()
3210 Reason = inet:posix() | invalid() | closed
3211 Backwards compatibility function.
3213 The same as setopt(Socket, {Level, Opt}, Value)
3215 setopt_native(Socket :: socket(),
3217 SocketOption ::
3218 socket_option() |
3219 {Level :: level() | (NativeLevel :: integer()),
3220 NativeOpt :: integer()},
3221 Value :: native_value()) ->
3222 ok | {error, posix() | invalid() | closed}
3223 Sets a socket option that may be unknown to our implementation,
3225 or that has a type not compatible with our implementation, that
3226 is; in "native mode".
3227 If Value is an integer() it will be used as a C type (int), if
3229 it is a boolean() it will be used as a C type (int) with the C
3230 implementations values for false or true, and if it is a bi‐
3231 nary() its content and size will be used as the option value.
3232 The socket option may be specified with an ordinary socket_op‐
3234 tion() tuple, with a known Level = level() and an integer Na‐
3235 tiveOpt, or with both an integer NativeLevel and NativeOpt.
3236 What options are valid depends on what kind of socket it is (do‐
3238 main(), type() and protocol()).
3239 The integer values for NativeLevel and NativeOpt as well as the
3241 encoding of Value has to be deduced from the header files for
3242 the running system.
3243 shutdown(Socket, How) -> ok | {error, Reason}
3245 Types:
3247 Socket = socket()
3249 How = read | write | read_write
3250 Reason = posix() | closed
3251 Shut down all or part of a full-duplex connection.
3253 sockname(Socket) -> {ok, SockAddr} | {error, Reason}
3255 Types:
3257 Socket = socket()
3259 SockAddr = sockaddr_recv()
3260 Reason = posix() | closed
3261 Returns the current address to which the socket is bound.
3263 supports() ->
3265 [{Key1 :: term(),
3266 boolean() |
3267 [{Key2 :: term(),
3268 boolean() | [{Key3 :: term(), boolean()}]}]}]
3269 supports(Key1 :: term()) ->
3271 [{Key2 :: term(),
3272 boolean() | [{Key3 :: term(), boolean()}]}]
3273 supports(Key1 :: term(), Key2 :: term()) ->
3275 [{Key3 :: term(), boolean()}]
3276 These functions function retreives information about what the
3278 platform supports, such which platform features or which socket
3279 options, are supported.
3280 For keys other than the known the empty list is returned, Note
3282 that in a future version or on a different platform there might
3283 be more supported items.
3284 supports():
3286 Returns a list of {Key1, supports(Key1)} tuples for every
3287 Key1 described in supports/1 and {Key1, boolean()} tuples
3288 for each of the following keys:
3289 sctp:
3291 SCTP support
3292 ipv6:
3294 IPv6 support
3295 local:
3297 Unix Domain sockets support (AF_UNIX | AF_LOCAL)
3298 netns:
3300 Network Namespaces support (Linux, setns(2))
3301 sendfile:
3303 Sendfile support (sendfile(2))
3304 supports(msg_flags = Key1):
3306 Returns a list of {Flag, boolean()} tuples for every Flag in
3307 msg_flag() with the boolean() indicating if the flag is sup‐
3308 ported on this platform.
3309 supports(protocols = Key1):
3311 Returns a list of {Name :: atom(), boolean()} tuples for ev‐
3312 ery Name in protocol() with the boolean() indicating if the
3313 protocol is supported on this platform.
3314 supports(options = Key1):
3316 Returns a list of {SocketOption, boolean()} tuples for every
3317 SocketOption in socket_option() with the boolean() indicat‐
3318 ing if the socket option is supported on this platform.
3319 supports(options = Key1, Key2) :
3321 For a Key2 in level() returns a list of {Opt, boolean()} tu‐
3322 ples for all known socket options Opt on that Level =:=
3323 Key2, and the boolean() indicating if the socket option is
3324 supported on this platform. See setopt/3 and getopt/2.
3325 use_registry(D :: boolean()) -> ok
3327 Globally change if the socket registry is to be used or not.
3329 Note that its still possible to override this explicitly when
3330 creating an individual sockets, see open/2 or open/4 for more
3331 info (use the Extra argument).
3332 which_sockets() -> [socket()]
3334 which_sockets(FilterRule) -> [socket()]
3336 Types:
3338 FilterRule =
3340 inet | inet6 | local | stream | dgram | seqpacket | sctp
3341 |
3342 tcp | udp |
3343 pid() |
3344 fun((socket_info()) -> boolean())
3345 Returns a list of all sockets, according to the filter rule.
3347 There are several pre-made filter rule(s) and one general:
3349 inet | inet6:
3351 Selection based on the domain of the socket.
3352 Only a subset is valid.
3353 stream | dgram | seqpacket:
3355 Selection based on the type of the socket.
3356 Only a subset is valid.
3357 sctp | tcp | udp:
3359 Selection based on the protocol of the socket.
3360 Only a subset is valid.
3361 pid():
3363 Selection base on which sockets has this pid as Controlling
3364 Process.
3365 fun((socket_info()) -> boolean()):
3367 The general filter rule.
3368 A fun that takes the socket info and returns a boolean()
3369 (true if the socket sould be included and false if should
3370 not).
3371
3373 client(SAddr, SPort) ->
3374 {ok, Sock} = socket:open(inet, stream, tcp),
3375 ok = socket:connect(Sock, #{family => inet,
3376 addr => SAddr,
3377 port => SPort}),
3378 Msg = <<"hello">>,
3379 ok = socket:send(Sock, Msg),
3380 ok = socket:shutdown(Sock, write),
3381 {ok, Msg} = socket:recv(Sock),
3382 ok = socket:close(Sock).
3383 server(Addr, Port) ->
3385 {ok, LSock} = socket:open(inet, stream, tcp),
3386 ok = socket:bind(LSock, #{family => inet,
3387 port => Port,
3388 addr => Addr}),
3389 ok = socket:listen(LSock),
3390 {ok, Sock} = socket:accept(LSock),
3391 {ok, Msg} = socket:recv(Sock),
3392 ok = socket:send(Sock, Msg),
3393 ok = socket:close(Sock),
3394 ok = socket:close(LSock).
3395Ericsson AB kernel 8.3.2 socket(3)