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_dl() |
190 sockaddr_unspec() |
191 sockaddr_native()
192 sockaddr_recv() = sockaddr() | binary()
194 sockaddr_in() =
196 #{family := inet,
197 port := port_number(),
198 addr := any | broadcast | loopback | in_addr()}
199 sockaddr_in6() =
201 #{family := inet6,
202 port := port_number(),
203 addr := any | loopback | in6_addr(),
204 flowinfo := in6_flow_info(),
205 scope_id := in6_scope_id()}
206 sockaddr_un() = #{family := local, path := binary() | string()}
208 The path element will always be a binary when returned from this
210 module. When supplied to an API function in this module it may
211 be a string(), which will be encoded into a binary according to
212 the native file name encoding on the platform.
213 A terminating zero character will be appended before the address
215 path is given to the OS, and the terminating zero will be
216 stripped before giving the address path to the caller.
217 Linux's non-portable abstract socket address extension is han‐
219 dled by not doing any terminating zero processing in either di‐
220 rection, if the first byte of the address is zero.
221 sockaddr_ll() =
223 #{family := packet,
224 protocol := integer() >= 0,
225 ifindex := integer(),
226 pkttype := packet_type(),
227 hatype := hatype(),
228 addr := binary()}
229 sockaddr_dl() =
231 #{family := link,
232 index := integer() >= 0,
233 type := integer() >= 0,
234 nlen := integer() >= 0,
235 alen := integer() >= 0,
236 slen := integer() >= 0,
237 data := binary()}
238 sockaddr_unspec() = #{family := unspec, addr := binary()}
240 sockaddr_native() = #{family := integer(), addr := binary()}
242 packet_type() =
244 host | broadcast | multicast | otherhost | outgoing |
245 loopback | user | kernel | fastroute |
246 integer() >= 0
247 hatype() =
249 netrom | eether | ether | ax25 | pronet | chaos | ieee802 |
250 arcnet | appletlk | dlci | atm | metricom | ieee1394 | eui64 |
251 infiniband | tunnel | tunnel6 | loopback | localtlk | none |
252 void |
253 integer() >= 0
254 port_number() = 0..65535
256 in6_flow_info() = 0..1048575
258 in6_scope_id() = 0..4294967295
260 msg_flag() =
262 cmsg_cloexec | confirm | ctrunc | dontroute | eor | errqueue |
263 more | oob | peek | trunc
264 Flags corresponding to the message flag constants on the plat‐
266 form. The flags are lowercase and the constants are uppercase
267 with the prefix MSG_.
268 Some flags are only used for sending, some only for receiving,
270 some in received control messages, and some for several of
271 these. Not all flags are supported on all platforms. See the
272 platform's documentation, supports(msg_flags), and is_sup‐
273 ported(msg_flags, MsgFlag).
274 level() = socket | protocol()
276 The OS protocol levels for, for example, socket options and con‐
278 trol messages, with the following names in the OS header files:
279 socket:
281 SOL_SOCKET with options named SO_*.
282 ip:
284 IPPROTO_IP a.k.a SOL_IP with options named IP_*.
285 ipv6:
287 IPPROTO_IPV6 a.k.a SOL_IPV6 with options named IPV6_*.
288 tcp:
290 IPPROTO_TCP with options named TCP_*.
291 udp:
293 IPPROTO_UDP with options named UDP_*.
294 sctp:
296 IPPROTO_SCTP with options named SCTP_*.
297 There are many other possible protocols, but the ones above are
299 those for which this socket library implements socket options
300 and/or control messages.
301 All protocols known to the OS are enumerated when the Erlang VM
303 is started. See the OS man page for protocols(5). The protocol
304 level 'socket' is always implemented as SOL_SOCKET and all the
305 others mentioned in the list above are valid, if supported by
306 the platform, enumerated or not.
307 The calls supports() and is_supported(protocols, Protocol) can
309 be used to find out if protocols ipv6 and/or sctp are supported
310 according to the platform's header files.
311 otp_socket_option() =
313 debug | iow | controlling_process | rcvbuf | rcvctrlbuf |
314 sndctrlbuf | meta | use_registry | fd | domain
315 These are socket options for the otp protocol level, that is
317 {otp, Name} options, above all OS protocol levels. They affect
318 Erlang/OTP's socket implementation.
319 debug:
321 boolean() - Activate debug printout.
322 iow:
324 boolean() - Inform On Wrap of statistics counters.
325 controlling_process:
327 pid() - The socket "owner". Only the current controlling
328 process can set this option.
329 rcvbuf:
331 BufSize :: (default | integer()>0) | {N :: integer()>0,
332 BufSize :: (default | integer()>0)} - Receive buffer size.
333 The value default is only valid to set. N specifies the num‐
334 ber of read attempts to do in a tight loop before assuming
335 no more data is pending.
336 rcvctrlbuf:
338 BufSize :: (default | integer()>0) - Buffer size for re‐
339 ceived ancillary messages. The value default is only valid
340 to set.
341 sndctrlbuf:
343 BufSize :: (default | integer()>0) - Buffer size for sent
344 ancillary messages. The value default is only valid to set.
345 fd:
347 integer() - Only valid to get. The OS protocol levels'
348 socket descriptor. Functions open/1,2 can be used to create
349 a socket according to this module from an existing OS socket
350 descriptor.
351 use_registry:
353 boolean() - Only valid to get. The value is set when the
354 socket is created with open/2 or open/4.
355 Options not described here are intentionally undocumented and
357 for Erlang/OTP internal use only.
358 socket_option() =
360 {Level :: socket,
361 Opt ::
362 acceptconn | acceptfilter | bindtodevice | broadcast |
363 busy_poll | debug | domain | dontroute | error |
364 keepalive | linger | mark | oobinline | passcred |
365 peek_off | peercred | priority | protocol | rcvbuf |
366 rcvbufforce | rcvlowat | rcvtimeo | reuseaddr |
367 reuseport | rxq_ovfl | setfib | sndbuf | sndbufforce |
368 sndlowat | sndtimeo | timestamp | type} |
369 {Level :: ip,
370 Opt ::
371 add_membership | add_source_membership | block_source |
372 dontfrag | drop_membership | drop_source_membership |
373 freebind | hdrincl | minttl | msfilter | mtu |
374 mtu_discover | multicast_all | multicast_if |
375 multicast_loop | multicast_ttl | nodefrag | options |
376 pktinfo | recvdstaddr | recverr | recvif | recvopts |
377 recvorigdstaddr | recvtos | recvttl | retopts |
378 router_alert | sndsrcaddr | tos | transparent | ttl |
379 unblock_source} |
380 {Level :: ipv6,
381 Opt ::
382 addrform | add_membership | authhdr | auth_level |
383 checksum | drop_membership | dstopts | esp_trans_level |
384 esp_network_level | faith | flowinfo | hopopts |
385 ipcomp_level | join_group | leave_group | mtu |
386 mtu_discover | multicast_hops | multicast_if |
387 multicast_loop | portrange | pktoptions | recverr |
388 recvhoplimit | hoplimit | recvpktinfo | pktinfo |
389 recvtclass | router_alert | rthdr | tclass |
390 unicast_hops | use_min_mtu | v6only} |
391 {Level :: tcp,
392 Opt ::
393 congestion | cork | info | keepcnt | keepidle |
394 keepintvl | maxseg | md5sig | nodelay | noopt | nopush |
395 syncnt | user_timeout} |
396 {Level :: udp, Opt :: cork} |
397 {Level :: sctp,
398 Opt ::
399 adaption_layer | associnfo | auth_active_key |
400 auth_asconf | auth_chunk | auth_key | auth_delete_key |
401 autoclose | context | default_send_params |
402 delayed_ack_time | disable_fragments | hmac_ident |
403 events | explicit_eor | fragment_interleave |
404 get_peer_addr_info | initmsg | i_want_mapped_v4_addr |
405 local_auth_chunks | maxseg | maxburst | nodelay |
406 partial_delivery_point | peer_addr_params |
407 peer_auth_chunks | primary_addr | reset_streams |
408 rtoinfo | set_peer_primary_addr | status |
409 use_ext_recvinfo}
410 Socket option on the form {Level, Opt} where the OS protocol
412 Level = level() and Opt is a socket option on that protocol
413 level.
414 The OS name for an options is, except where otherwise noted, the
416 Opt atom, in capitals, with prefix according to level().
417 Note:
419 The IPv6 option pktoptions is a special (barf) case. It is in‐
420 tended for backward compatibility usage only.
421 Do not use this option.
423 Note:
426 See the OS documentation for every socket option.
427 An option below that has the value type boolean() will translate
430 the value false to a C int with value 0, and the value true to
431 !!0 (not (not false)).
432 An option with value type integer() will be translated to a C
434 int that may have a restricted range, for example byte: 0..255.
435 See the OS documentation.
436 The calls supports(options), supports(options, Level) and
438 is_supported(options, {Level, Opt}) can be used to find out
439 which socket options that are supported by the platform.
440 Options for protocol level socket:
442 {socket, acceptconn}:
444 Value = boolean()
445 {socket, bindtodevice}:
447 Value = string()
448 {socket, broadcast}:
450 Value = boolean()
451 {socket, debug}:
453 Value = integer()
454 {socket, domain}:
456 Value = domain()
457 Only valid to get.
459 The socket's protocol domain. Does not work on for instance
461 FreeBSD.
462 {socket, dontroute}:
464 Value = boolean()
465 {socket, keepalive}:
467 Value = boolean()
468 {socket, linger}:
470 Value = abort | linger()
471 The value abort is shorthand for #{onoff => true, linger =>
473 0}, and only valid to set.
474 {socket, oobinline}:
476 Value = boolean()
477 {socket, passcred}:
479 Value = boolean()
480 {socket, peek_off}:
482 Value = integer()
483 Currently disabled due to a possible infinite loop when
485 calling recv/1-4 with peek in Flags.
486 {socket, priority}:
488 Value = integer()
489 {socket, protocol}:
491 Value = protocol()
492 Only valid to get.
494 The socket's protocol. Does not work on for instance Darwin.
496 {socket, rcvbuf}:
498 Value = integer()
499 {socket, rcvlowat}:
501 Value = integer()
502 {socket, rcvtimeo}:
504 Value = timeval()
505 This option is unsupported per default; OTP has to be ex‐
507 plicitly built with the --enable-esock-rcvsndtimeo configure
508 option for this to be available.
509 Since our implementation uses nonblocking sockets, it is un‐
511 known if and how this option works, or even if it may cause
512 malfunction. Therefore, we do not recommend setting this op‐
513 tion.
514 Instead, use the Timeout argument to, for instance, the
516 recv/3 function.
517 {socket, reuseaddr}:
519 Value = boolean()
520 {socket, reuseport}:
522 Value = boolean()
523 {socket, sndbuf}:
525 Value = integer()
526 {socket, sndlowat}:
528 Value = integer()
529 {socket, sndtimeo}:
531 Value = timeval()
532 This option is unsupported per default; OTP has to be ex‐
534 plicitly built with the --enable-esock-rcvsndtimeo configure
535 option for this to be available.
536 Since our implementation uses nonblocking sockets, it is un‐
538 known if and how this option works, or even if it may cause
539 malfunction. Therefore, we do not recommend setting this op‐
540 tion.
541 Instead, use the Timeout argument to, for instance, the
543 send/3 function.
544 {socket, timestamp}:
546 Value = boolean()
547 {socket, type}:
549 Value = type()
550 Only valid to get.
552 The socket's type.
554 Options for protocol level ip:
556 {ip, add_membership}:
558 Value = ip_mreq()
559 Only valid to set.
561 {ip, add_source_membership}:
563 Value = ip_mreq_source()
564 Only valid to set.
566 {ip, block_source}:
568 Value = ip_mreq_source()
569 Only valid to set.
571 {ip, drop_membership}:
573 Value = ip_mreq()
574 Only valid to set.
576 {ip, drop_source_membership}:
578 Value = ip_mreq_source()
579 Only valid to set.
581 {ip, freebind}:
583 Value = boolean()
584 {ip, hdrincl}:
586 Value = boolean()
587 {ip, minttl}:
589 Value = integer()
590 {ip, msfilter}:
592 Value = null | ip_msfilter()
593 Only valid to set.
595 The value null passes a NULL pointer and size 0 to the C li‐
597 brary call.
598 {ip, mtu}:
600 Value = integer()
601 Only valid to get.
603 {ip, mtu_discover}:
605 Value = ip_pmtudisc() | integer()
606 An integer() value is according to the platform's header
608 files.
609 {ip, multicast_all}:
611 Value = boolean()
612 {ip, multicast_if}:
614 Value = any | in_addr()
615 {ip, multicast_loop}:
617 Value = boolean()
618 {ip, multicast_ttl}:
620 Value = integer()
621 {ip, nodefrag}:
623 Value = boolean()
624 {ip, pktinfo}:
626 Value = boolean()
627 {ip, recvdstaddr}:
629 Value = boolean()
630 {ip, recverr}:
632 Value = boolean()
633 Warning! When this option is enabled, error messages may ar‐
635 rive on the socket's error queue, which should be read using
636 the message flag errqueue, and using recvmsg/1,2,3,4,5 to
637 get all error information in the message's ctrl field as a
638 control message #{level := ip, type := recverr}.
639 A working strategy should be to first poll the error queue
641 using recvmsg/2,3,4 with Timeout =:= 0 and Flags containing
642 errqueue (ignore the return value {error, timeout}) before
643 reading the actual data to ensure that the error queue gets
644 cleared. And read the data using one of the nowait | se‐
645 lect_handle() recv functions: recv/3,4, recvfrom/3,4 or
646 recvmsg/3,4,5. Otherwise you might accidentally cause a busy
647 loop in and out of 'select' for the socket.
648 {ip, recvif}:
650 Value = boolean()
651 {ip, recvopts}:
653 Value = boolean()
654 {ip, recvorigdstaddr}:
656 Value = boolean()
657 {ip, recvtos}:
659 Value = boolean()
660 {ip, recvttl}:
662 Value = boolean()
663 {ip, retopts}:
665 Value = boolean()
666 {ip, router_alert}:
668 Value = integer()
669 {ip, sendsrcaddr}:
671 Value = boolean()
672 {ip, tos}:
674 Value = ip_tos() | integer()
675 An integer() value is according to the platform's header
677 files.
678 {ip, transparent}:
680 Value = boolean()
681 {ip, ttl}:
683 Value = integer()
684 {ip, unblock_source}:
686 Value = ip_mreq_source()
687 Only valid to set.
689 Options for protocol level ipv6:
691 {ipv6, addrform}:
693 Value = domain()
694 As far as we know the only valid value is inet and it is
696 only allowed for an IPv6 socket that is connected and bound
697 to an IPv4-mapped IPv6 address.
698 {ipv6, add_membership}:
700 Value = ipv6_mreq()
701 Only valid to set.
703 {ipv6, authhdr}:
705 Value = boolean()
706 {ipv6, drop_membership}:
708 Value = ipv6_mreq()
709 Only valid to set.
711 {ipv6, dstopts}:
713 Value = boolean()
714 {ipv6, flowinfo}:
716 Value = boolean()
717 {ipv6, hoplimit}:
719 Value = boolean()
720 {ipv6, hopopts}:
722 Value = boolean()
723 {ipv6, mtu}:
725 Value = integer()
726 {ipv6, mtu_discover}:
728 Value = ipv6_pmtudisc() | integer()
729 An integer() value is according to the platform's header
731 files.
732 {ipv6, multicast_hops}:
734 Value = ipv6_hops()
735 {ipv6, multicast_if}:
737 Value = integer()
738 {ipv6, multicast_loop}:
740 Value = boolean()
741 {ipv6, recverr}:
743 Value = boolean()
744 Warning! See the socket option {ip, recverr} regarding the
746 socket's error queue. The same warning applies for this op‐
747 tion.
748 {ipv6, recvhoplimit}:
750 Value = boolean()
751 {ipv6, recvpktinfo}:
753 Value = boolean()
754 {ipv6, recvtclass}:
756 Value = boolean()
757 {ipv6, router_alert}:
759 Value = integer()
760 {ipv6, rthdr}:
762 Value = boolean()
763 {ipv6, tclass}:
765 Value = boolean()
766 {ipv6, unicast_hops}:
768 Value = ipv6_hops()
769 {ipv6, v6only}:
771 Value = boolean()
772 Options for protocol level sctp. See also RFC 6458.
774 {sctp, associnfo}:
776 Value = sctp_assocparams()
777 {sctp, autoclose}:
779 Value = integer()
780 {sctp, disable_fragments}:
782 Value = boolean()
783 {sctp, events}:
785 Value = sctp_event_subscribe()
786 Only valid to set.
788 {sctp, initmsg}:
790 Value = sctp_initmsg()
791 {sctp, maxseg}:
793 Value = integer()
794 {sctp, nodelay}:
796 Value = boolean()
797 {sctp, rtoinfo}:
799 Value = sctp_rtoinfo()
800 Options for protocol level tcp:
802 {tcp, congestion}:
804 Value = string()
805 {tcp, cork}:
807 Value = boolean()
808 {tcp, maxseg}:
810 Value = integer()
811 {tcp, nodelay}:
813 Value = boolean()
814 Options for protocol level udp:
816 {udp, cork}:
818 Value = boolean()
819 linger() = #{onoff := boolean(), linger := integer() >= 0}
821 Corresponds to the C struct linger for managing the socket op‐
823 tion {socket, linger}.
824 timeval() = #{sec := integer(), usec := integer()}
826 Corresponds to the C struct timeval. The field sec holds sec‐
828 onds, and usec microseconds.
829 ip_mreq() = #{multiaddr := in_addr(), interface := in_addr()}
831 Corresponds to the C struct ip_mreq for managing multicast
833 groups.
834 ip_mreq_source() =
836 #{multiaddr := in_addr(),
837 interface := in_addr(),
838 sourceaddr := in_addr()}
839 Corresponds to the C struct ip_mreq_source for managing multi‐
841 cast groups.
842 ip_msfilter() =
844 #{multiaddr := in_addr(),
845 interface := in_addr(),
846 mode := include | exclude,
847 slist := [in_addr()]}
848 Corresponds to the C struct ip_msfilter for managing multicast
850 source filtering (RFC 3376).
851 ip_pmtudisc() = want | dont | do | probe
853 Lowercase atom() values corresponding to the C library constants
855 IP_PMTUDISC_*. Some constant(s) may be unsupported by the plat‐
856 form.
857 ip_tos() = lowdelay | throughput | reliability | mincost
859 Lowercase atom() values corresponding to the C library constants
861 IPTOS_*. Some constant(s) may be unsupported by the platform.
862 ip_pktinfo() =
864 #{ifindex := integer() >= 0,
865 spec_dst := in_addr(),
866 addr := in_addr()}
867 ipv6_mreq() =
869 #{multiaddr := in6_addr(), interface := integer() >= 0}
870 Corresponds to the C struct ipv6_mreq for managing multicast
872 groups. See also RFC 2553.
873 ipv6_hops() = default | 0..255
875 The value default is only valid to set and is translated to the
877 C value -1, meaning the route default.
878 ipv6_pmtudisc() = want | dont | do | probe
880 Lowercase atom() values corresponding to the C library constants
882 IPV6_PMTUDISC_*. Some constant(s) may be unsupported by the
883 platform.
884 ipv6_pktinfo() = #{addr := in6_addr(), ifindex := integer()}
886 sctp_assocparams() =
888 #{assoc_id := integer(),
889 asocmaxrxt := 0..65535,
890 numbe_peer_destinations := 0..65535,
891 peer_rwnd := 0..4294967295,
892 local_rwnd := 0..4294967295,
893 cookie_life := 0..4294967295}
894 Corresponds to the C struct sctp_assocparams.
896 sctp_event_subscribe() =
898 #{data_io := boolean(),
899 association := boolean(),
900 address := boolean(),
901 send_failure := boolean(),
902 peer_error := boolean(),
903 shutdown := boolean(),
904 partial_delivery := boolean(),
905 adaptation_layer => boolean(),
906 sender_dry => boolean()}
907 Corresponds to the C struct sctp_event_subscribe.
909 Not all fields are implemented on all platforms; unimplemented
911 fields are ignored, but implemented fields are mandatory. Note
912 that the '_event' suffixes have been stripped from the C struct
913 field names, for convenience.
914 sctp_initmsg() =
916 #{num_ostreams := 0..65535,
917 max_instreams := 0..65535,
918 max_attempts := 0..65535,
919 max_init_timeo := 0..65535}
920 Corresponds to the C struct sctp_initmsg.
922 sctp_rtoinfo() =
924 #{assoc_id := integer(),
925 initial := 0..4294967295,
926 max := 0..4294967295,
927 min := 0..4294967295}
928 Corresponds to the C struct sctp_rtoinfo.
930 msg() = msg_send() | msg_recv()
932 msg_send() =
934 #{addr => sockaddr(),
935 iov := erlang:iovec(),
936 ctrl =>
937 [cmsg_send() |
938 #{level := level() | integer(),
939 type := integer(),
940 data := binary()}]}
941 Message sent by sendmsg/2,3,4.
943 Corresponds to a C struct msghdr, see your platform documenta‐
945 tion for sendmsg(2).
946 addr:
948 Optional peer address, used on unconnected sockets. Corre‐
949 sponds to msg_name and msg_namelen fields of a struct ms‐
950 ghdr. If not used they are set to NULL, 0.
951 iov:
953 Mandatory data as a list of binaries. The msg_iov and
954 msg_iovlen fields of a struct msghdr.
955 ctrl:
957 Optional list of control messages (CMSG). Corresponds to
958 the msg_control and msg_controllen fields of a struct ms‐
959 ghdr. If not used they are set to NULL, 0.
960 The msg_flags field of the struct msghdr is set to 0.
962 msg_recv() =
964 #{addr => sockaddr_recv(),
965 iov := erlang:iovec(),
966 ctrl :=
967 [cmsg_recv() |
968 #{level := level() | integer(),
969 type := integer(),
970 data := binary()}],
971 flags := [msg_flag() | integer()]}
972 Message returned by recvmsg/1,2,3,5.
974 Corresponds to a C struct msghdr, see your platform documenta‐
976 tion for recvmsg(2).
977 addr:
979 Optional peer address, used on unconnected sockets. Corre‐
980 sponds to msg_name and msg_namelen fields of a struct ms‐
981 ghdr. If NULL the map key is not present.
982 iov:
984 Data as a list of binaries. The msg_iov and msg_iovlen
985 fields of a struct msghdr.
986 ctrl:
988 A possibly empty list of control messages (CMSG). Corre‐
989 sponds to the msg_control and msg_controllen fields of a
990 struct msghdr.
991 flags:
993 Message flags. Corresponds to the msg_flags field of a
994 struct msghdr. Unknown flags, if any, are returned in one
995 integer(), last in the containing list.
996 native_value() = integer() | boolean() | binary()
998 cmsg_send() =
1000 #{level := socket,
1001 type := timestamp,
1002 data => native_value(),
1003 value => timeval()} |
1004 #{level := socket, type := rights, data := native_value()} |
1005 #{level := socket,
1006 type := credentials,
1007 data := native_value()} |
1008 #{level := ip,
1009 type := tos,
1010 data => native_value(),
1011 value => ip_tos() | integer()} |
1012 #{level := ip,
1013 type := ttl,
1014 data => native_value(),
1015 value => integer()} |
1016 #{level := ip,
1017 type := hoplimit,
1018 data => native_value(),
1019 value => integer()} |
1020 #{level := ipv6,
1021 type := tclass,
1022 data => native_value(),
1023 value => integer()}
1024 Control messages (ancillary messages) accepted by sendmsg/2,3,4.
1026 A control message may for some message types have a value field
1028 with a symbolic value, or a data field with a native value, that
1029 has to be binary compatible what is defined in the platform's
1030 header files.
1031 cmsg_recv() =
1033 #{level := socket,
1034 type := timestamp,
1035 data := binary(),
1036 value => timeval()} |
1037 #{level := socket, type := rights, data := binary()} |
1038 #{level := socket, type := credentials, data := binary()} |
1039 #{level := ip,
1040 type := tos,
1041 data := binary(),
1042 value => ip_tos() | integer()} |
1043 #{level := ip,
1044 type := recvtos,
1045 data := binary(),
1046 value := ip_tos() | integer()} |
1047 #{level := ip,
1048 type := ttl,
1049 data := binary(),
1050 value => integer()} |
1051 #{level := ip,
1052 type := recvttl,
1053 data := binary(),
1054 value := integer()} |
1055 #{level := ip,
1056 type := pktinfo,
1057 data := binary(),
1058 value => ip_pktinfo()} |
1059 #{level := ip,
1060 type := origdstaddr,
1061 data := binary(),
1062 value => sockaddr_recv()} |
1063 #{level := ip,
1064 type := recverr,
1065 data := binary(),
1066 value => extended_err()} |
1067 #{level := ipv6,
1068 type := hoplimit,
1069 data := binary(),
1070 value => integer()} |
1071 #{level := ipv6,
1072 type := pktinfo,
1073 data := binary(),
1074 value => ipv6_pktinfo()} |
1075 #{level := ipv6,
1076 type := recverr,
1077 data := binary(),
1078 value => extended_err()} |
1079 #{level := ipv6,
1080 type := tclass,
1081 data := binary(),
1082 value => integer()}
1083 Control messages (ancillary messages) returned by
1085 recvmsg/1,2,3,5.
1086 A control message has got a data field with a native (binary)
1088 value for the message data, and may also have a decoded value
1089 field if this socket library successfully decoded the data.
1090 icmp_dest_unreach() =
1092 net_unreach | host_unreach | port_unreach | frag_needed |
1093 net_unknown | host_unknown
1094 icmpv6_dest_unreach() =
1096 noroute | adm_prohibited | not_neighbour | addr_unreach |
1097 port_unreach | policy_fail | reject_route
1098 ee_origin() = none | local | icmp | icmp6
1100 extended_err() =
1102 #{error := posix(),
1103 origin := icmp,
1104 type := dest_unreach,
1105 code := icmp_dest_unreach() | 0..255,
1106 info := 0..4294967295,
1107 data := 0..4294967295,
1108 offender := sockaddr_recv()} |
1109 #{error := posix(),
1110 origin := icmp,
1111 type := time_exceeded | 0..255,
1112 code := 0..255,
1113 info := 0..4294967295,
1114 data := 0..4294967295,
1115 offender := sockaddr_recv()} |
1116 #{error := posix(),
1117 origin := icmp6,
1118 type := dest_unreach,
1119 code := icmpv6_dest_unreach() | 0..255,
1120 info := 0..4294967295,
1121 data := 0..4294967295,
1122 offender := sockaddr_recv()} |
1123 #{error := posix(),
1124 origin := icmp6,
1125 type := pkt_toobig | time_exceeded | 0..255,
1126 code := 0..255,
1127 info := 0..4294967295,
1128 data := 0..4294967295,
1129 offender := sockaddr_recv()} |
1130 #{error := posix(),
1131 origin := ee_origin() | 0..255,
1132 type := 0..255,
1133 code := 0..255,
1134 info := 0..4294967295,
1135 data := 0..4294967295,
1136 offender := sockaddr_recv()}
1137 posix() = inet:posix()
1139 The POSIX error codes originates from the OS level socket inter‐
1141 face.
1142
1144 accept(ListenSocket) -> {ok, Socket} | {error, Reason}
1145 accept(ListenSocket, Timeout :: infinity) ->
1147 {ok, Socket} | {error, Reason}
1148 Types:
1150 ListenSocket = Socket = socket()
1152 Reason = posix() | closed | invalid()
1153 Accept a connection on a socket.
1155 This call is used with connection oriented socket types (stream
1157 or seqpacket). It returns the first pending incoming connection
1158 for a listen socket, or waits for one to arrive, and returns the
1159 (newly) connected socket.
1160 accept(ListenSocket, Timeout :: integer() >= 0) ->
1162 {ok, Socket} | {error, Reason}
1163 Types:
1165 ListenSocket = Socket = socket()
1167 Reason = posix() | closed | invalid() | timeout
1168 The same as accept/1 but returns {error, timeout} if no connec‐
1170 tion has been accepted after Timeout milliseconds.
1171 Note:
1173 Note that if multiple calls are made only the last call is
1174 "valid":
1175 {select, {select_info, _Handle}} = socket:accept(LSock, nowait),
1177 {error, timeout} = socket:accept(LSock, 500),
1178 .
1179 .
1180 .
1181 In the example above, Handle is not valid once the second (ac‐
1184 cept-) call has been made (the first call is automatically "can‐
1185 celled" and an abort messaage sent, when the second call is
1186 made). After the (accept-) call resulting in the timeout has
1187 been made, there is no longer an active accept call!
1188 accept(ListenSocket, Timeout :: nowait) ->
1191 {ok, Socket} | {select, SelectInfo} | {error, Reason}
1192 accept(ListenSocket, SelectHandle :: select_handle()) ->
1194 {ok, Socket} | {select, SelectInfo} | {error, Reason}
1195 Types:
1197 ListenSocket = Socket = socket()
1199 SelectInfo = select_info()
1200 Reason = posix() | closed | invalid()
1201 The same as accept/1 but returns promptly.
1203 When there is no pending connection to return, the function will
1205 return {select, SelectInfo}, and the caller will later receive a
1206 select message, {'$socket', Socket, select, SelectHandle} ( with
1207 the SelectHandle contained in the SelectInfo ) when a client
1208 connects. A subsequent call to accept/1,2 will then return the
1209 socket.
1210 If the time-out argument is SelectHandle, that term will be con‐
1212 tained in a returned SelectInfo and the corresponding select
1213 message. The SelectHandle is presumed to be unique to this call.
1214 If the time-out argument is nowait, and a SelectInfo is re‐
1216 turned, it will contain a select_handle() generated by the call.
1217 If the caller doesn't want to wait for a connection, it must im‐
1219 mediately call cancel/2 to cancel the operation.
1220 Note:
1222 Note that if multiple calls are made only the last call is
1223 "valid":
1224 {select, {select_info, _Handle1}} = socket:accept(LSock, nowait),
1226 {select, {select_info, _Handle2}} = socket:accept(LSock, nowait),
1227 receive
1228 {'$socket', LSock, select, Handle2} ->
1229 {ok, ASock} = socket:accept(LSock, nowait),
1230 .
1231 .
1232 .
1233 end
1234 In the example above, only Handle2 is valid once the second (ac‐
1237 cept-) call has been made (the first call is automatically "can‐
1238 celled" and an abort messaage sent, when the second call is
1239 made).
1240 bind(Socket, Addr) -> ok | {error, Reason}
1243 Types:
1245 Socket = socket()
1247 Addr = sockaddr() | any | broadcast | loopback
1248 Reason = posix() | closed | invalid()
1249 Bind a name to a socket.
1251 When a socket is created (with open), it has no address assigned
1253 to it. bind assigns the address specified by the Addr argument.
1254 The rules used for name binding vary between domains.
1256 If you bind a socket to an address in for example the 'inet' or
1258 'inet6' address families, with an ephemeral port number (0), and
1259 want to know which port that was chosen, you can find out using
1260 something like: {ok, #{port := Port}} = socket:sockname(Socket)
1261 cancel(Socket, SelectInfo) -> ok | {error, Reason}
1263 Types:
1265 Socket = socket()
1267 SelectInfo = select_info()
1268 Reason = closed | invalid()
1269 Cancel an asynchronous request.
1271 Call this function in order to cancel a previous asynchronous
1273 call to, e.g. recv/3.
1274 An ongoing asynchronous operation blocks the socket until the
1276 operation has been finished in good order, or until it has been
1277 cancelled by this function.
1278 Any other process that tries an operation of the same basic type
1280 (accept / send / recv) will be enqueued and notified with the
1281 regular select mechanism for asynchronous operations when the
1282 current operation and all enqueued before it has been completed.
1283 If SelectInfo does not match an operation in progress for the
1285 calling process, this function returns {error, {invalid, Select‐
1286 Info}}.
1287 close(Socket) -> ok | {error, Reason}
1289 Types:
1291 Socket = socket()
1293 Reason = posix() | closed | timeout
1294 Closes the socket.
1296 Note:
1298 Note that for e.g. protocol = tcp, most implementations doing a
1299 close does not guarantee that any data sent is delivered to the
1300 recipient before the close is detected at the remote side.
1301 One way to handle this is to use the shutdown function
1303 (socket:shutdown(Socket, write)) to signal that no more data is
1304 to be sent and then wait for the read side of the socket to be
1305 closed.
1306 connect(Socket, SockAddr) -> ok | {error, Reason}
1309 connect(Socket, SockAddr, Timeout :: infinity) ->
1311 ok | {error, Reason}
1312 Types:
1314 Socket = socket()
1316 SockAddr = sockaddr()
1317 Reason = posix() | closed | invalid() | already
1318 This function connects the socket to the address specified by
1320 the SockAddr argument, and returns when the connection has been
1321 established or failed.
1322 If a connection attempt is already in progress (by another
1324 process), {error, already} is returned.
1325 connect(Socket, SockAddr, Timeout :: integer() >= 0) ->
1327 ok | {error, Reason}
1328 Types:
1330 Socket = socket()
1332 SockAddr = sockaddr()
1333 Reason = posix() | closed | invalid() | already | timeout
1334 The same as connect/2 but returns {error, timeout} if no connec‐
1336 tion has been established after Timeout milliseconds.
1337 Note:
1339 Note that when this call has returned {error, timeout} the con‐
1340 nection state of the socket is uncertain since the platform's
1341 network stack may complete the connection at any time, up to
1342 some platform specific time-out.
1343 Repeating a connection attempt towards the same address would be
1345 ok, but towards a different address could end up with a connec‐
1346 tion to either address.
1347 The safe play would be to close the socket and start over.
1349 Also note that all this applies to cancelling a connect call
1351 with a no-wait time-out described below.
1352 connect(Socket, SockAddr, Timeout :: nowait) ->
1355 ok | {select, SelectInfo} | {error, Reason}
1356 connect(Socket, SockAddr, SelectHandle :: select_handle()) ->
1358 ok | {select, SelectInfo} | {error, Reason}
1359 Types:
1361 Socket = socket()
1363 SockAddr = sockaddr()
1364 SelectInfo = select_info()
1365 Reason = posix() | closed | invalid() | already
1366 The same as connect/2 but returns promptly.
1368 If it is not possible to immediately establish a connection, the
1370 function will return {select, SelectInfo}, and the caller will
1371 later receive a select message, {'$socket', Socket, select, Se‐
1372 lectHandle} ( with the SelectHandle contained in the SelectInfo
1373 ) when the connection has been completed or failed. A subsequent
1374 call to connect/1 will then finalize the connection and return
1375 the result.
1376 If the time-out argument is SelectHandle, that term will be con‐
1378 tained in a returned SelectInfo and the corresponding select
1379 message. The SelectHandle is presumed to be unique to this call.
1380 If the time-out argument is nowait, and a SelectInfo is re‐
1382 turned, it will contain a select_handle() generated by the call.
1383 If the caller doesn't want to wait for the connection to com‐
1385 plete, it must immediately call cancel/2 to cancel the opera‐
1386 tion.
1387 connect(Socket) -> ok | {error, Reason}
1389 Types:
1391 Socket = socket()
1393 Reason = posix() | closed | invalid()
1394 This function finalizes a connection setup on a socket, after
1396 calling connect(_, _, nowait | select_handle()) that returned
1397 {select, SelectInfo}, and receiving the select message
1398 {'$socket', Socket, select, SelectHandle}, and returns whether
1399 the connection setup was successful or not.
1400 Instead of calling this function, for backwards compatibility,
1402 it is allowed to call connect/2,3, but that incurs more overhead
1403 since the connect address and time-out are processed in vain.
1404 cancel_monitor(MRef) -> boolean()
1406 Types:
1408 MRef = reference()
1410 If MRef is a reference that the calling process obtained by
1412 calling monitor/1, this monitor is turned off. If the monitoring
1413 is already turned off, nothing happens.
1414 The returned value is one of the following:
1416 true:
1418 The monitor was found and removed. In this case, no 'DOWN'
1419 message corresponding to this monitor has been delivered and
1420 will not be delivered.
1421 false:
1423 The monitor was not found and could not be removed. This
1424 probably because a 'DOWN' message corresponding to this mon‐
1425 itor has already been placed in the caller message queue.
1426 Failure: It is an error if MRef refers to a monitor started by
1428 another process.
1429 getopt(X1 :: socket(),
1431 SocketOption :: {Level :: otp, Opt :: otp_socket_option()}) ->
1432 {ok, Value :: term()} | {error, invalid() | closed}
1433 Gets a socket option from the protocol level otp, which is this
1435 implementation's level above the OS protocol layers.
1436 See the type otp_socket_option() for a description of the op‐
1438 tions on this level.
1439 getopt(X1 :: socket(), SocketOption :: socket_option()) ->
1441 {ok, Value :: term()} |
1442 {error, posix() | invalid() | closed}
1443 Gets a socket option from one of the OS's protocol levels. See
1445 the type socket_option() for which options that this implementa‐
1446 tion knows about, how they are related to option names in the
1447 OS, and if there are known peculiarities with any of them.
1448 What options are valid depends on what kind of socket it is (do‐
1450 main(), type() and protocol()).
1451 See the socket options chapter of the users guide for more
1453 info.
1454 Note:
1456 Not all options are valid, nor possible to get, on all plat‐
1457 forms. That is, even if "we" support an option; it does not mean
1458 that the underlying OS does.
1459 getopt(Socket, Level, Opt) -> ok | {error, Reason}
1462 Types:
1464 Socket = socket()
1466 Reason = inet:posix() | invalid() | closed
1467 Backwards compatibility function.
1469 The same as getopt(Socket, {Level, Opt})
1471 getopt_native(X1 :: socket(),
1473 SocketOption ::
1474 socket_option() |
1475 {Level :: level() | (NativeLevel :: integer()),
1476 NativeOpt :: integer()},
1477 ValueType :: integer) ->
1478 {ok, Value :: integer()} |
1479 {error, posix() | invalid() | closed}
1480 getopt_native(X1 :: socket(),
1482 SocketOption ::
1483 socket_option() |
1484 {Level :: level() | (NativeLevel :: integer()),
1485 NativeOpt :: integer()},
1486 ValueType :: boolean) ->
1487 {ok, Value :: boolean()} |
1488 {error, posix() | invalid() | closed}
1489 getopt_native(X1 :: socket(),
1491 SocketOption ::
1492 socket_option() |
1493 {Level :: level() | (NativeLevel :: integer()),
1494 NativeOpt :: integer()},
1495 ValueSize :: integer() >= 0) ->
1496 {ok, Value :: binary()} |
1497 {error, posix() | invalid() | closed}
1498 getopt_native(X1 :: socket(),
1500 SocketOption ::
1501 socket_option() |
1502 {Level :: level() | (NativeLevel :: integer()),
1503 NativeOpt :: integer()},
1504 ValueSpec :: binary()) ->
1505 {ok, Value :: binary()} |
1506 {error, posix() | invalid() | closed}
1507 Gets a socket option that may be unknown to our implementation,
1509 or that has a type not compatible with our implementation, that
1510 is; in "native mode".
1511 The socket option may be specified with an ordinary socket_op‐
1513 tion() tuple, with a known Level = level() and an integer Na‐
1514 tiveOpt, or with both an integer NativeLevel and NativeOpt.
1515 How to decode the option value has to be specified either with
1517 ValueType, by specifying the ValueSize for a binary() that will
1518 contain the fetched option value, or by specifying a binary()
1519 ValueSpec that will be copied to a buffer for the getsockopt()
1520 call to write the value in which will be returned as a new bi‐
1521 nary().
1522 If ValueType is integer a C type (int) will be fetched, if it is
1524 boolean a C type (int) will be fetched and converted into a
1525 boolean() according to the C implementation.
1526 What options are valid depends on what kind of socket it is (do‐
1528 main(), type() and protocol()).
1529 The integer values for NativeLevel and NativeOpt as well as the
1531 Value encoding has to be deduced from the header files for the
1532 running system.
1533 i() -> ok
1535 Print all sockets in table format in the erlang shell.
1537 i(InfoKeys) -> ok
1539 Types:
1541 InfoKeys = info_keys()
1543 Print all sockets in table format in the erlang shell. What in‐
1545 formation is included is defined by InfoKeys.
1546 i(Domain) -> ok
1548 Types:
1550 Domain = inet | inet6 | local
1552 Print a selection, based on domain, of the sockets in table for‐
1554 mat in the erlang shell.
1555 i(Proto) -> ok
1557 Types:
1559 Proto = sctp | tcp | udp
1561 Print a selection, based on protocol, of the sockets in table
1563 format in the erlang shell.
1564 i(Type) -> ok
1566 Types:
1568 Type = dgram | seqpacket | stream
1570 Print a selection, based on type, of the sockets in table format
1572 in the erlang shell.
1573 i(Domain, InfoKeys) -> ok
1575 Types:
1577 Domain = inet | inet6 | local
1579 InfoKeys = info_keys()
1580 Print a selection, based on domain, of the sockets in table for‐
1582 mat in the erlang shell. What information is included is defined
1583 by InfoKeys.
1584 i(Proto, InfoKeys) -> ok
1586 Types:
1588 Proto = sctp | tcp | udp
1590 InfoKeys = info_keys()
1591 Print a selection, based on domain, of the sockets in table for‐
1593 mat in the erlang shell. What information is included is defined
1594 by InfoKeys.
1595 i(Type, InfoKeys) -> ok
1597 Types:
1599 Type = dgram | seqpacket | stream
1601 InfoKeys = info_keys()
1602 Print a selection, based on type, of the sockets in table format
1604 in the erlang shell. What information is included is defined by
1605 InfoKeys.
1606 info() -> info()
1608 Get miscellaneous info about the socket library.
1610 The function returns a map with each info item as a key-value
1612 binding.
1613 Note:
1615 In order to ensure data integrity, mutex'es are taken when
1616 needed. So, do not call this function often.
1617 info(Socket) -> socket_info()
1620 Types:
1622 Socket = socket()
1624 Get miscellaneous info about the socket.
1626 The function returns a map with each info item as a key-value
1628 binding. It reflects the "current" state of the socket.
1629 Note:
1631 In order to ensure data integrity, mutex'es are taken when
1632 needed. So, do not call this function often.
1633 ioctl(Socket, GetRequest) -> {ok, IFConf} | {error, Reason}
1636 Types:
1638 Socket = socket()
1640 GetRequest = gifconf
1641 IFConf = [#{name := string, addr := sockaddr()}]
1642 Reason = posix() | closed
1643 Retrieve socket (device) parameters.
1645 ioctl(Socket, GetRequest, NameOrIndex) ->
1647 {ok, Result} | {error, Reason}
1648 Types:
1650 Socket = socket()
1652 GetRequest =
1653 gifname | gifindex | gifaddr | gifdstaddr | gifbrdaddr |
1654 gifnetmask | gifhwaddr | gifmtu | giftxqlen | gifflags
1655 NameOrIndex = string() | integer()
1656 Result = term()
1657 Reason = posix() | closed
1658 Retrieve socket (device) parameters. This function retrieves a
1660 specific parameter, according to GetRequest argument. The third
1661 argument is the (lookup) "key", identifying the interface (usu‐
1662 ally the name of the interface).
1663 gifname:
1665 Get the name of the interface with the specified index (in‐
1666 teger()).
1667 Result, name of the interface, is a string().
1669 gifindex:
1671 Get the index of the interface with the specified name.
1672 Result, interface index, is a integer().
1674 gifaddr:
1676 Get the address of the interface with the specified name.
1677 Result, address of the interface, is a socket:sockaddr().
1678 gifdstaddr:
1680 Get the destination address of the point-to-point interface
1681 with the specified name.
1682 Result, destination address of the interface, is a
1684 socket:sockaddr().
1685 gifbrdaddr:
1687 Get the droadcast address for the interface with the speci‐
1688 fied name.
1689 Result, broadcast address of the interface, is a
1691 socket:sockaddr().
1692 gifnetmask:
1694 Get the network mask for the interface with the specified
1695 name.
1696 Result, network mask of the interface, is a socket:sock‐
1698 addr().
1699 gifhwaddr:
1701 Get the hardware address for the interface with the speci‐
1702 fied name.
1703 Result, hardware address of the interface, is a socket:sock‐
1705 addr(). The family field contains the 'ARPHRD' device type
1706 (or an integer).
1707 gifmtu:
1709 Get the MTU (Maximum Transfer Unit) for the interface with
1710 the specified name.
1711 Result, MTU of the interface, is an integer().
1713 giftxqlen:
1715 Get the transmit queue length of the interface with the
1716 specified name.
1717 Result, transmit queue length of the interface, is an inte‐
1719 ger().
1720 gifflags:
1722 Get the active flag word of the interface with the specified
1723 name.
1724 Result, the active flag word of the interface, is an list of
1726 socket:ioctl_device_flag() | integer().
1727 ioctl(Socket, SetRequest, Name, Value) -> ok | {error, Reason}
1729 Types:
1731 Socket = socket()
1733 SetRequest =
1734 sifflags | sifaddr | sifdstaddr | sifbrdaddr | sifnetmask
1735 |
1736 sifhwaddr | gifmtu | siftxqlen
1737 Name = string()
1738 Value = term()
1739 Reason = posix() | closed
1740 Set socket (device) parameters. This function sets a specific
1742 parameter, according to SetRequest argument. The third argument
1743 is the "key", identifying the interface (usually the name of the
1744 interface), and the fourth is the "new" value.
1745 These are privileged operation's.
1747 sifflags:
1749 Set the the active flag word, #{Flag => boolean()}, of the
1750 interface with the specified name.
1751 Each flag to be changed, should be added to the value map,
1753 with the value 'true' if the flag (Flag) should be set and
1754 'false' if the flag should be reset.
1755 sifaddr:
1757 Set the address, sockaddr(), of the interface with the spec‐
1758 ified name.
1759 sifdstaddr:
1761 Set the destination address, sockaddr(), of a point-to-point
1762 interface with the specified name.
1763 sifbrdaddr:
1765 Set the broadcast address, sockaddr(), of the interface with
1766 the specified name.
1767 sifnetmask:
1769 Set the network mask, sockaddr(), of the interface with the
1770 specified name.
1771 sifmtu:
1773 Set the MTU (Maximum Transfer Unit), integer(), for the in‐
1774 terface with the specified name.
1775 siftxqlen:
1777 Set the transmit queue length, integer(), of the interface
1778 with the specified name.
1779 is_supported(Key1 :: term()) -> boolean()
1781 is_supported(Key1 :: term(), Key2 :: term()) -> boolean()
1783 This function retrieves information about what the platform sup‐
1785 ports, such as if SCTP is supported, or if a socket options are
1786 supported.
1787 For keys other than the known false is returned. Note that in a
1789 future version or on a different platform there might be more
1790 supported items.
1791 This functions returns a boolean corresponding to what sup‐
1793 ports/0-2 reports for the same Key1 (and Key2).
1794 listen(Socket) -> ok | {error, Reason}
1796 listen(Socket, Backlog) -> ok | {error, Reason}
1798 Types:
1800 Socket = socket()
1802 Backlog = integer()
1803 Reason = posix() | closed
1804 Listen for connections on a socket.
1806 monitor(Socket) -> reference()
1808 Types:
1810 Socket = socket()
1812 Start monitor the socket Socket.
1814 If the monitored socket does not exist or when the monitor is
1816 triggered, a 'DOWN' message is sent that has the following pat‐
1817 tern:
1818 {'DOWN', MonitorRef, socket, Object, Info}
1820 In the monitor message MonitorRef and Type are the same as de‐
1823 scribed earlier, and:
1824 Object:
1826 The monitored entity, socket, which triggered the event.
1827 Info:
1829 Either the termination reason of the socket or nosock
1830 (socket Socket did not exist at the time of monitor cre‐
1831 ation).
1832 Making several calls to socket:monitor/1 for the same Socket is
1834 not an error; it results in as many independent monitoring in‐
1835 stances.
1836 number_of() -> integer() >= 0
1838 Returns the number of active sockets.
1840 open(FD) -> {ok, Socket} | {error, Reason}
1842 open(FD, Opts) -> {ok, Socket} | {error, Reason}
1844 Types:
1846 FD = integer()
1848 Opts =
1849 #{domain => domain() | integer(),
1850 type => type() | integer(),
1851 protocol => default | protocol() | integer(),
1852 dup => boolean(),
1853 debug => boolean(),
1854 use_registry => boolean()}
1855 Socket = socket()
1856 Reason = posix() | domain | type | protocol
1857 Creates an endpoint (socket) for communication based on an al‐
1859 ready existing file descriptor. The function attempts to re‐
1860 trieve domain, type and protocol from the system. This is how‐
1861 ever not possible on all platforms, and they should then be
1862 specified in Opts.
1863 The Opts argument is intended for providing extra information
1865 for the open call:
1866 domain:
1868 Which protocol domain is the descriptor of. See also
1869 open/2,3,4.
1870 type:
1872 Which protocol type type is the descriptor of.
1873 See also open/2,3,4.
1875 protocol:
1877 Which protocol is the descriptor of. The atom default is
1878 equivalent to the integer protocol number 0 which means the
1879 default protocol for a given domain and type.
1880 If the protocol can not be retrieved from the platform for
1882 the socket, and protocol is not specified, the default pro‐
1883 tocol is used, which may or may not be correct.
1884 See also open/2,3,4.
1886 dup:
1888 Shall the provided descriptor be duplicated (dup) or not.
1889 Defaults to true.
1890 debug:
1892 Enable or disable debug during the open call.
1893 Defaults to false.
1894 use_registry>:
1896 Enable or disable use of the socket registry for this
1897 socket. This overrides the global value.
1898 Defaults to the global value, see use_registry/1.
1899 Note:
1901 This function should be used with care!
1902 On some platforms it is necessary to provide domain, type and
1904 protocol since they cannot be retrieved from the platform.
1905 open(Domain, Type) -> {ok, Socket} | {error, Reason}
1908 open(Domain, Type, Opts) -> {ok, Socket} | {error, Reason}
1910 Types:
1912 Domain = domain() | integer()
1914 Type = type() | integer()
1915 Opts = map()
1916 Socket = socket()
1917 Reason = posix() | protocol
1918 Creates an endpoint (socket) for communication.
1920 The same as open(Domain, Type, default) and open(Domain, Type,
1922 default, Opts) respectively.
1923 open(Domain, Type, Protocol) -> {ok, Socket} | {error, Reason}
1925 open(Domain, Type, Protocol, Opts) ->
1927 {ok, Socket} | {error, Reason}
1928 Types:
1930 Domain = domain() | integer()
1932 Type = type() | integer()
1933 Protocol = default | protocol() | integer()
1934 Opts =
1935 #{netns => string(),
1936 debug => boolean(),
1937 use_registry => boolean()}
1938 Socket = socket()
1939 Reason = posix() | protocol
1940 Creates an endpoint (socket) for communication.
1942 Domain and Type may be integer()s, as defined in the platform's
1944 header files. The same goes for Protocol as defined in the plat‐
1945 form's services(5) database. See also the OS man page for the
1946 library call socket(2).
1947 Note:
1949 For some combinations of Domain and Type the platform has got a
1950 default protocol that can be selected with Protocol = default,
1951 and the platform may allow or require selecting the default pro‐
1952 tocol, a specific protocol, or either.
1953 Examples:
1955 socket:open(inet, stream, tcp):
1957 It is common that for protocol domain and type inet,stream
1958 it is allowed to select the tcp protocol although that
1959 mostly is the default.
1960 socket:open(local, dgram):
1962 It is common that for the protocol domain local it is manda‐
1963 tory to not select a protocol, that is; to select the de‐
1964 fault protocol.
1965 The Opts argument is intended for "other" options. The supported
1968 option(s) are described below:
1969 netns: string():
1971 Used to set the network namespace during the open call. Only
1972 supported on the Linux platform.
1973 debug: boolean():
1975 Enable or disable debug during the open call.
1976 Defaults to false.
1977 use_registry: boolean():
1979 Enable or disable use of the socket registry for this
1980 socket. This overrides the global value.
1981 Defaults to the global value, see use_registry/1.
1982 peername(Socket) -> {ok, SockAddr} | {error, Reason}
1984 Types:
1986 Socket = socket()
1988 SockAddr = sockaddr_recv()
1989 Reason = posix() | closed
1990 Returns the address of the peer connected to the socket.
1992 recv(Socket) ->
1994 {ok, Data} | {error, Reason} | {error, {Reason, Data}}
1995 recv(Socket, Flags) ->
1997 {ok, Data} | {error, Reason} | {error, {Reason, Data}}
1998 recv(Socket, Length) ->
2000 {ok, Data} | {error, Reason} | {error, {Reason, Data}}
2001 recv(Socket, Flags, Timeout :: infinity) ->
2003 {ok, Data} | {error, Reason} | {error, {Reason, Data}}
2004 recv(Socket, Length, Flags) ->
2006 {ok, Data} | {error, Reason} | {error, {Reason, Data}}
2007 recv(Socket, Length, Timeout :: infinity) ->
2009 {ok, Data} | {error, Reason} | {error, {Reason, Data}}
2010 recv(Socket, Length, Flags, Timeout :: infinity) ->
2012 {ok, Data} | {error, Reason} | {error, {Reason, Data}}
2013 Types:
2015 Socket = socket()
2017 Length = integer() >= 0
2018 Flags = [msg_flag() | integer()]
2019 Data = binary()
2020 Reason = posix() | closed | invalid()
2021 Receives data from a socket, waiting for it to arrive.
2023 The argument Length specifies how many bytes to receive, with
2025 the special case 0 meaning "all available".
2026 For a socket of type stream this call will not return until all
2028 requested data can be delivered, or if "all available" data was
2029 requested when the first data chunk arrives.
2030 The message Flags may be symbolic msg_flag()s and/or integer()s,
2032 as in the platform's appropriate header files. The values of all
2033 symbolic flags and integers are or:ed together.
2034 When there is a socket error this function returns {error, Rea‐
2036 son}, or if some data arrived before the error; {error, {Reason,
2037 Data}}.
2038 recv(Socket, Flags, Timeout :: integer() >= 0) ->
2040 {ok, Data} | {error, Reason} | {error, {Reason, Data}}
2041 recv(Socket, Length, Timeout :: integer() >= 0) ->
2043 {ok, Data} | {error, Reason} | {error, {Reason, Data}}
2044 recv(Socket, Length, Flags, Timeout :: integer() >= 0) ->
2046 {ok, Data} | {error, Reason} | {error, {Reason, Data}}
2047 Types:
2049 Socket = socket()
2051 Length = integer() >= 0
2052 Flags = [msg_flag() | integer()]
2053 Data = binary()
2054 Reason = posix() | closed | invalid() | timeout
2055 Receives data from a socket, waiting at most Timeout millisec‐
2057 onds for it to arrive.
2058 The same as infinite time-out recv/1,2,3,4 but returns {error,
2060 timeout} or {error, {timeout, Data}} after Timeout milliseconds,
2061 if the requested data has not been delivered.
2062 recv(Socket, Flags, SelectHandle :: nowait) ->
2064 {ok, Data} |
2065 {select, SelectInfo} |
2066 {select, {SelectInfo, Data}} |
2067 {error, Reason} |
2068 {error, {Reason, Data}}
2069 recv(Socket, Flags, SelectHandle :: select_handle()) ->
2071 {ok, Data} |
2072 {select, SelectInfo} |
2073 {select, {SelectInfo, Data}} |
2074 {error, Reason} |
2075 {error, {Reason, Data}}
2076 recv(Socket, Length, SelectHandle :: nowait) ->
2078 {ok, Data} |
2079 {select, SelectInfo} |
2080 {select, {SelectInfo, Data}} |
2081 {error, Reason} |
2082 {error, {Reason, Data}}
2083 recv(Socket, Length, SelectHandle :: select_handle()) ->
2085 {ok, Data} |
2086 {select, SelectInfo} |
2087 {select, {SelectInfo, Data}} |
2088 {error, Reason} |
2089 {error, {Reason, Data}}
2090 recv(Socket, Length, Flags, SelectHandle :: nowait) ->
2092 {ok, Data} |
2093 {select, SelectInfo} |
2094 {select, {SelectInfo, Data}} |
2095 {error, Reason} |
2096 {error, {Reason, Data}}
2097 recv(Socket, Length, Flags, SelectHandle :: select_handle()) ->
2099 {ok, Data} |
2100 {select, SelectInfo} |
2101 {select, {SelectInfo, Data}} |
2102 {error, Reason} |
2103 {error, {Reason, Data}}
2104 Types:
2106 Socket = socket()
2108 Length = integer() >= 0
2109 Flags = [msg_flag() | integer()]
2110 Data = binary()
2111 SelectInfo = select_info()
2112 Reason = posix() | closed | invalid()
2113 Receives data from a socket, but returns a select continuation
2115 if the data could not be returned immediately.
2116 The same as infinite time-out recv/1,2,3,4 but if the data can‐
2118 not be delivered immediately, the function returns {select, Se‐
2119 lectInfo}, and the caller will then receive a select message,
2120 {'$socket', Socket, select, SelectHandle} ( with the Selec‐
2121 tHandle contained in the SelectInfo ) when data has arrived. A
2122 subsequent call to recv/1,2,3,4 will then return the data.
2123 If the time-out argument is SelectHandle, that term will be con‐
2125 tained in a returned SelectInfo and the corresponding select
2126 message. The SelectHandle is presumed to be unique to this call.
2127 If the time-out argument is nowait, and a SelectInfo is re‐
2129 turned, it will contain a select_handle() generated by the call.
2130 Note that for a socket of type stream, if Length > 0 and only
2132 part of that amount of data is available, the function will re‐
2133 turn {ok, {Data, SelectInfo with partial data. If the caller
2134 doesn't want to wait for more data, it must immediately call
2135 cancel/2 to cancel the operation.
2136 recvfrom(Socket) -> {ok, {Source, Data}} | {error, Reason}
2138 recvfrom(Socket, Flags) -> {ok, {Source, Data}} | {error, Reason}
2140 recvfrom(Socket, BufSz) -> {ok, {Source, Data}} | {error, Reason}
2142 recvfrom(Socket, Flags, Timeout :: infinity) ->
2144 {ok, {Source, Data}} | {error, Reason}
2145 recvfrom(Socket, BufSz, Flags) ->
2147 {ok, {Source, Data}} | {error, Reason}
2148 recvfrom(Socket, BufSz, Timeout :: infinity) ->
2150 {ok, {Source, Data}} | {error, Reason}
2151 recvfrom(Socket, BufSz, Flags, Timeout :: infinity) ->
2153 {ok, {Source, Data}} | {error, Reason}
2154 Types:
2156 Socket = socket()
2158 BufSz = integer() >= 0
2159 Flags = [msg_flag() | integer()]
2160 Source = sockaddr_recv()
2161 Data = binary()
2162 Reason = posix() | closed | invalid()
2163 Receive a message from a socket, waiting for it to arrive.
2165 The function returns when a message is received, or when there
2167 is a socket error. Argument BufSz specifies the number of bytes
2168 for the receive buffer. If the buffer size is too small, the
2169 message will be truncated.
2170 If BufSz is not specified or 0, a default buffer size is used,
2172 which can be set by socket:setopt(Socket, {otp,recvbuf}, BufSz).
2173 If it is impossible to know the appropriate buffer size, it may
2175 be possible to use the receive message flag peek. When this flag
2176 is used, the message is not "consumed" from the underlying buf‐
2177 fers, so another recvfrom/1,2,3,4 call is needed, possibly with
2178 an adjusted buffer size.
2179 The message Flags may be symbolic msg_flag()s and/or integer()s,
2181 as in the platform's appropriate header files. The values of all
2182 symbolic flags and integers are or:ed together.
2183 recvfrom(Socket, Flags, Timeout :: integer() >= 0) ->
2185 {ok, {Source, Data}} | {error, Reason}
2186 recvfrom(Socket, BufSz, Timeout :: integer() >= 0) ->
2188 {ok, {Source, Data}} | {error, Reason}
2189 recvfrom(Socket, BufSz, Flags, Timeout :: integer() >= 0) ->
2191 {ok, {Source, Data}} | {error, Reason}
2192 Types:
2194 Socket = socket()
2196 BufSz = integer() >= 0
2197 Flags = [msg_flag() | integer()]
2198 Source = sockaddr_recv()
2199 Data = binary()
2200 Reason = posix() | closed | invalid() | timeout
2201 Receives a message from a socket, waiting at most Timeout mil‐
2203 liseconds for it to arrive.
2204 The same as infinite time-out recvfrom/1,2,3,4 but returns {er‐
2206 ror, timeout} after Timeout milliseconds, if no message has been
2207 delivered.
2208 recvfrom(Socket, Flags, SelectHandle :: nowait) ->
2210 {ok, {Source, Data}} |
2211 {select, SelectInfo} |
2212 {error, Reason}
2213 recvfrom(Socket, Flags, SelectHandle :: select_handle()) ->
2215 {ok, {Source, Data}} |
2216 {select, SelectInfo} |
2217 {error, Reason}
2218 recvfrom(Socket, BufSz, SelectHandle :: nowait) ->
2220 {ok, {Source, Data}} |
2221 {select, SelectInfo} |
2222 {error, Reason}
2223 recvfrom(Socket, BufSz, SelectHandle :: select_handle()) ->
2225 {ok, {Source, Data}} |
2226 {select, SelectInfo} |
2227 {error, Reason}
2228 recvfrom(Socket, BufSz, Flags, SelectHandle :: nowait) ->
2230 {ok, {Source, Data}} |
2231 {select, SelectInfo} |
2232 {error, Reason}
2233 recvfrom(Socket, BufSz, Flags, SelectHandle :: select_handle()) ->
2235 {ok, {Source, Data}} |
2236 {select, SelectInfo} |
2237 {error, Reason}
2238 Types:
2240 Socket = socket()
2242 BufSz = integer() >= 0
2243 Flags = [msg_flag() | integer()]
2244 Source = sockaddr_recv()
2245 Data = binary()
2246 SelectInfo = select_info()
2247 Reason = posix() | closed | invalid()
2248 Receives a message from a socket, but returns a select continua‐
2250 tion if no message could be returned immediately.
2251 The same as infinite time-out recvfrom/1,2,3,4 but if no mes‐
2253 sage cannot delivered immediately, the function returns {select,
2254 SelectInfo}, and the caller will then receive a select message,
2255 {'$socket', Socket, select, SelectHandle} ( with the Selec‐
2256 tHandle contained in the SelectInfo ) when data has arrived. A
2257 subsequent call to recvfrom/1,2,3,4 will then return the mes‐
2258 sage.
2259 If the time-out argument is SelectHandle, that term will be con‐
2261 tained in a returned SelectInfo and the corresponding select
2262 message. The SelectHandle is presumed to be unique to this call.
2263 If the time-out argument is nowait, and a SelectInfo is re‐
2265 turned, it will contain a select_handle() generated by the call.
2266 If the caller doesn't want to wait for the data, it must immedi‐
2268 ately call cancel/2 to cancel the operation.
2269 recvmsg(Socket) -> {ok, Msg} | {error, Reason}
2271 recvmsg(Socket, Flags) -> {ok, Msg} | {error, Reason}
2273 recvmsg(Socket, Timeout :: infinity) ->
2275 {ok, Msg} | {error, Reason}
2276 recvmsg(Socket, Flags, Timeout :: infinity) ->
2278 {ok, Msg} | {error, Reason}
2279 recvmsg(Socket, BufSz, CtrlSz) -> {ok, Msg} | {error, Reason}
2281 recvmsg(Socket, BufSz, CtrlSz, Timeout :: infinity) ->
2283 {ok, Msg} | {error, Reason}
2284 recvmsg(Socket, BufSz, CtrlSz, Flags, Timeout :: infinity) ->
2286 {ok, Msg} | {error, Reason}
2287 Types:
2289 Socket = socket()
2291 BufSz = CtrlSz = integer() >= 0
2292 Flags = [msg_flag() | integer()]
2293 Msg = msg_recv()
2294 Reason = posix() | closed | invalid()
2295 Receive a message from a socket, waiting for it to arrive.
2297 The function returns when a message is received, or when there
2299 is a socket error. Arguments BufSz and CtrlSz specifies the num‐
2300 ber of bytes for the receive buffer and the control message buf‐
2301 fer. If the buffer size(s) is(are) too small, the message and/or
2302 control message list will be truncated.
2303 If BufSz is not specified or 0, a default buffer size is used,
2305 which can be set by socket:setopt(Socket, {otp,recvbuf}, BufSz).
2306 The same applies to CtrlSz and socket:setopt(Socket, {otp,recvc‐
2307 trlbuf}, CtrlSz).
2308 If it is impossible to know the appropriate buffer size, it may
2310 be possible to use the receive message flag peek. When this flag
2311 is used, the message is not "consumed" from the underlying buf‐
2312 fers, so another recvfrom/1,2,3,4,5 call is needed, possibly
2313 with an adjusted buffer size.
2314 The message Flags may be symbolic msg_flag()s and/or integer()s,
2316 as in the platform's appropriate header files. The values of all
2317 symbolic flags and integers are or:ed together.
2318 recvmsg(Socket, Timeout :: integer() >= 0) ->
2320 {ok, Msg} | {error, Reason}
2321 recvmsg(Socket, Flags, Timeout :: integer() >= 0) ->
2323 {ok, Msg} | {error, Reason}
2324 recvmsg(Socket, BufSz, CtrlSz, Timeout :: integer() >= 0) ->
2326 {ok, Msg} | {error, Reason}
2327 recvmsg(Socket, BufSz, CtrlSz, Flags,
2329 Timeout :: integer() >= 0) ->
2330 {ok, Msg} | {error, Reason}
2331 Types:
2333 Socket = socket()
2335 BufSz = CtrlSz = integer() >= 0
2336 Flags = [msg_flag() | integer()]
2337 Msg = msg_recv()
2338 Reason = posix() | closed | invalid() | timeout
2339 Receives a message from a socket, waiting at most Timeout mil‐
2341 liseconds for it to arrive.
2342 The same as recvmsg/1,2,3,4,5 but returns {error, timeout} after
2344 Timeout milliseconds, if no message has been delivered.
2345 recvmsg(Socket, Timeout :: nowait) ->
2347 {ok, Msg} | {select, SelectInfo} | {error, Reason}
2348 recvmsg(Socket, SelectHandle :: select_handle()) ->
2350 {ok, Msg} | {select, SelectInfo} | {error, Reason}
2351 recvmsg(Socket, Flags, Timeout :: nowait) ->
2353 {ok, Msg} | {select, SelectInfo} | {error, Reason}
2354 recvmsg(Socket, Flags, SelectHandle :: select_handle()) ->
2356 {ok, Msg} | {select, SelectInfo} | {error, Reason}
2357 recvmsg(Socket, BufSz, CtrlSz, SelectHandle :: nowait) ->
2359 {ok, Msg} | {select, SelectInfo} | {error, Reason}
2360 recvmsg(Socket, BufSz, CtrlSz, SelectHandle :: select_handle()) ->
2362 {ok, Msg} | {select, SelectInfo} | {error, Reason}
2363 recvmsg(Socket, BufSz, CtrlSz, Flags, SelectHandle :: nowait) ->
2365 {ok, Msg} | {select, SelectInfo} | {error, Reason}
2366 recvmsg(Socket, BufSz, CtrlSz, Flags,
2368 SelectHandle :: select_handle()) ->
2369 {ok, Msg} | {select, SelectInfo} | {error, Reason}
2370 Types:
2372 Socket = socket()
2374 BufSz = CtrlSz = integer() >= 0
2375 Flags = [msg_flag() | integer()]
2376 Msg = msg_recv()
2377 SelectInfo = select_info()
2378 Reason = posix() | closed | invalid()
2379 Receives a message from a socket, but returns a select continua‐
2381 tion if no message could be returned immediately.
2382 The same as infinite time-out recvfrom/1,2,3,4 but if no mes‐
2384 sage cannot delivered immediately, the function returns {select,
2385 SelectInfo}, and the caller will then receive a select message,
2386 {'$socket', Socket, select, SelectHandle} ( with the Selec‐
2387 tHandle contained in the SelectInfo ) when data has arrived. A
2388 subsequent call to recvmsg/1,2,3,4,5 will then return the data.
2389 If the time-out argument is SelectHandle, that term will be con‐
2391 tained in a returned SelectInfo and the corresponding select
2392 message. The SelectHandle is presumed to be unique to this call.
2393 If the time-out argument is nowait, and a SelectInfo is re‐
2395 turned, it will contain a select_handle() generated by the call.
2396 If the caller doesn't want to wait for the data, it must immedi‐
2398 ately call cancel/2 to cancel the operation.
2399 send(Socket, Data) ->
2401 ok |
2402 {ok, RestData} |
2403 {error, Reason} |
2404 {error, {Reason, RestData}}
2405 send(Socket, Data, Flags) ->
2407 ok |
2408 {ok, RestData} |
2409 {error, Reason} |
2410 {error, {Reason, RestData}}
2411 send(Socket, Data, Timeout :: infinity) ->
2413 ok |
2414 {ok, RestData} |
2415 {error, Reason} |
2416 {error, {Reason, RestData}}
2417 send(Socket, Data, Flags, Timeout :: infinity) ->
2419 ok |
2420 {ok, RestData} |
2421 {error, Reason} |
2422 {error, {Reason, RestData}}
2423 Types:
2425 Socket = socket()
2427 Data = iodata()
2428 Flags = [msg_flag() | integer()]
2429 RestData = binary()
2430 Reason = posix() | closed | invalid()
2431 Sends data on a connected socket, waiting for it to be sent.
2433 This call will not return until the Data has been accepted by
2435 the platform's network layer, or it reports an error.
2436 The message Flags may be symbolic msg_flag()s and/or integer()s,
2438 matching the platform's appropriate header files. The values of
2439 all symbolic flags and integers are or:ed together.
2440 The Data, if it is not a binary(), is copied into one before
2442 calling the platform network API, because a single buffer is re‐
2443 quired. A returned RestData is a sub binary of this data binary.
2444 The return value indicates the result from the platform's net‐
2446 work layer:
2447 ok:
2449 All data has been accepted.
2450 {ok, RestData}:
2452 Not all data has been accepted, but no error has been re‐
2453 ported. RestData is the tail of Data that has not been ac‐
2454 cepted.
2455 This cannot happen for a socket of type stream where a par‐
2457 tially successful send is retried until the data is either
2458 accepted or there is an error.
2459 For a socket of type dgram this should probably also not
2461 happen since a message that cannot be passed atomically
2462 should render an error.
2463 It is nevertheless possible for the platform's network layer
2465 to return this.
2466 {error, Reason}:
2468 An error has been reported and no data has been accepted.
2469 The posix() Reasons are from the platform's network layer.
2470 closed means that this socket library knows that the socket
2471 is closed, and invalid() means that something about an argu‐
2472 ment is invalid.
2473 {error, {Reason, RestData}} :
2475 An error has been reported but before that some data was ac‐
2476 cepted. RestData is the tail of Data that has not been ac‐
2477 cepted. See {error, Reason} above.
2478 This can only happen for a socket of type stream when a par‐
2480 tially successful send is retried until there is an error.
2481 send(Socket, Data, Timeout :: integer() >= 0) ->
2483 ok |
2484 {ok, RestData} |
2485 {error, Reason | timeout} |
2486 {error, {Reason | timeout, RestData}}
2487 send(Socket, Data, Flags, Timeout :: integer() >= 0) ->
2489 ok |
2490 {ok, RestData} |
2491 {error, Reason | timeout} |
2492 {error, {Reason | timeout, RestData}}
2493 Types:
2495 Socket = socket()
2497 Data = iodata()
2498 Flags = [msg_flag() | integer()]
2499 RestData = binary()
2500 Reason = posix() | closed | invalid()
2501 Sends data on a connected socket, waiting at most Timeout mil‐
2503 liseconds for it to be sent.
2504 The same as infinite time-out send/2,3,4 but returns {error,
2506 timeout} or {error, {timeout, RestData}} after Timeout millisec‐
2507 onds, if no Data or only some of it was accepted by the plat‐
2508 form's network layer.
2509 send(Socket, Data, SelectHandle :: nowait) ->
2511 ok |
2512 {ok, RestData} |
2513 {select, SelectInfo} |
2514 {select, {SelectInfo, RestData}} |
2515 {error, Reason}
2516 send(Socket, Data, SelectHandle :: select_handle()) ->
2518 ok |
2519 {ok, RestData} |
2520 {select, SelectInfo} |
2521 {select, {SelectInfo, RestData}} |
2522 {error, Reason}
2523 send(Socket, Data, Flags, SelectHandle :: nowait) ->
2525 ok |
2526 {ok, RestData} |
2527 {select, SelectInfo} |
2528 {select, {SelectInfo, RestData}} |
2529 {error, Reason}
2530 send(Socket, Data, Flags, SelectHandle :: select_handle()) ->
2532 ok |
2533 {ok, RestData} |
2534 {select, SelectInfo} |
2535 {select, {SelectInfo, RestData}} |
2536 {error, Reason}
2537 Types:
2539 Socket = socket()
2541 Data = iodata()
2542 Flags = [msg_flag() | integer()]
2543 RestData = binary()
2544 SelectInfo = select_info()
2545 Reason = posix() | closed | invalid()
2546 Sends data on a connected socket, but returns a select continua‐
2548 tion if the data could not be sent immediately.
2549 The same as infinite time-out send/2,3 but if the data is not
2551 immediately accepted by the platform network layer, the function
2552 returns {select, SelectInfo}, and the caller will then receive a
2553 select message, {'$socket', Socket, select, SelectHandle} ( with
2554 the SelectHandle that was contained in the SelectInfo ) when
2555 there is room for more data. A subsequent call to send/2-4 will
2556 then send the data.
2557 If SelectHandle is a select_handle(), that term will be con‐
2559 tained in a returned SelectInfo and the corresponding select
2560 message. The SelectHandle is presumed to be unique to this call.
2561 If SelectHandle is nowait, and a SelectInfo is returned, it will
2563 contain a select_handle() generated by the call.
2564 If some of the data was sent, the function will return {ok,
2566 {RestData, SelectInfo}, which can only happen for a socket of
2567 type stream. If the caller does not want to wait to send the
2568 rest of the data, it should immediately cancel the operation
2569 with cancel/2.
2570 send(Socket, Data, Cont) ->
2572 ok |
2573 {ok, RestData} |
2574 {error, Reason} |
2575 {error, {Reason, RestData}}
2576 send(Socket, Data, Cont, Timeout :: infinity) ->
2578 ok |
2579 {ok, RestData} |
2580 {error, Reason} |
2581 {error, {Reason, RestData}}
2582 send(Socket, Data, Cont, Timeout :: integer() >= 0) ->
2584 ok |
2585 {ok, RestData} |
2586 {error, Reason | timeout} |
2587 {error, {Reason | timeout, RestData}}
2588 send(Socket, Data, Cont, SelectHandle :: nowait) ->
2590 ok |
2591 {ok, RestData} |
2592 {select, SelectInfo} |
2593 {select, {SelectInfo, RestData}} |
2594 {error, Reason}
2595 send(Socket, Data, Cont, SelectHandle :: select_handle()) ->
2597 ok |
2598 {ok, RestData} |
2599 {select, SelectInfo} |
2600 {select, {SelectInfo, RestData}} |
2601 {error, Reason}
2602 Types:
2604 Socket = socket()
2606 Data = iodata()
2607 Cont = select_info()
2608 RestData = binary()
2609 SelectInfo = select_info()
2610 Reason = posix() | closed | invalid()
2611 Continues sending data on a connected socket, where the send op‐
2613 eration was initiated by send/3,4 that returned a SelectInfo
2614 continuation. Otherwise like infinite time-out send/2,3,4 ,
2615 limited time-out send/3,4 or nowait send/3,4 respectively.
2616 Cont is the SelectInfo that was returned from the previous
2618 send() call.
2619 If Data is not a binary(), it will be copied into one, again.
2621 The return value indicates the result from the platform's net‐
2623 work layer. See send/2,3,4 and nowait send/3,4.
2624 sendmsg(Socket, Msg) ->
2626 ok |
2627 {ok, RestData} |
2628 {error, Reason} |
2629 {error, {Reason, RestData}}
2630 sendmsg(Socket, Msg, Flags) ->
2632 ok |
2633 {ok, RestData} |
2634 {error, Reason} |
2635 {error, {Reason, RestData}}
2636 sendmsg(Socket, Msg, Timeout :: infinity) ->
2638 ok |
2639 {ok, RestData} |
2640 {error, Reason} |
2641 {error, {Reason, RestData}}
2642 sendmsg(Socket, Msg, Flags, Timeout :: infinity) ->
2644 ok |
2645 {ok, RestData} |
2646 {error, Reason} |
2647 {error, {Reason, RestData}}
2648 Types:
2650 Socket = socket()
2652 Msg = msg_send()
2653 Flags = [msg_flag() | integer()]
2654 RestData = erlang:iovec()
2655 Reason = posix() | closed | invalid()
2656 Sends a message on a socket, waiting for it to be sent.
2658 The destination, if needed, that is: if the socket is not con‐
2660 nected, is provided in Msg, which also contains the data to send
2661 as a list of binaries. Msg may also contain an list of optional
2662 control messages (depending on what the protocol and platform
2663 supports).
2664 For a connected socket no address field should be present in
2666 Msg, the platform may return an error or ignore one.
2667 The message data is given to to the platform's network layer in
2669 the form of an I/O vector without copying the content. If the
2670 number of elements in the I/O vector is larger than allowed on
2671 the platform (reported in the iov_max field from info/0), on a
2672 socket of type stream the send is iterated over all elements,
2673 but for other socket types the call fails.
2674 This call will not return until the data has been handed over to
2676 the platform's network layer, or when it reports an error.
2677 The message Flags may be symbolic msg_flag()s and/or integer()s,
2679 matching the platform's appropriate header files. The values of
2680 all symbolic flags and integers are or:ed together.
2681 The return value indicates the result from the platform's net‐
2683 work layer. See send/2,3,4.
2684 sendmsg(Socket, Msg, Timeout :: integer() >= 0) ->
2686 ok |
2687 {ok, RestData} |
2688 {error, Reason | timeout} |
2689 {error, {Reason | timeout, RestData}}
2690 sendmsg(Socket, Msg, Flags, Timeout :: integer() >= 0) ->
2692 ok |
2693 {ok, RestData} |
2694 {error, Reason | timeout} |
2695 {error, {Reason | timeout, RestData}}
2696 Types:
2698 Socket = socket()
2700 Msg = msg_send()
2701 Flags = [msg_flag() | integer()]
2702 RestData = erlang:iovec()
2703 Reason = posix() | closed | invalid()
2704 Sends a message on a socket, waiting at most Timeout millisec‐
2706 onds for it to be sent.
2707 The same as infinite time-out sendmsg/2,3,4 but returns {error,
2709 timeout} or {error, {timeout, RestData}} after Timeout millisec‐
2710 onds, if no data or only some of it was accepted by the plat‐
2711 form's network layer.
2712 sendmsg(Socket, Msg, Timeout :: nowait) ->
2714 ok |
2715 {ok, RestData} |
2716 {select, SelectInfo} |
2717 {select, {SelectInfo, RestData}} |
2718 {error, Reason} |
2719 {error, {Reason, RestData}}
2720 sendmsg(Socket, Msg, SelectHandle :: select_handle()) ->
2722 ok |
2723 {ok, RestData} |
2724 {select, SelectInfo} |
2725 {select, {SelectInfo, RestData}} |
2726 {error, Reason} |
2727 {error, {Reason, RestData}}
2728 sendmsg(Socket, Msg, Flags, SelectHandle :: nowait) ->
2730 ok |
2731 {ok, RestData} |
2732 {select, SelectInfo} |
2733 {select, {SelectInfo, RestData}} |
2734 {error, Reason} |
2735 {error, {Reason, RestData}}
2736 sendmsg(Socket, Msg, Flags, SelectHandle :: select_handle()) ->
2738 ok |
2739 {ok, RestData} |
2740 {select, SelectInfo} |
2741 {select, {SelectInfo, RestData}} |
2742 {error, Reason} |
2743 {error, {Reason, RestData}}
2744 Types:
2746 Socket = socket()
2748 Msg = msg_send()
2749 Flags = [msg_flag() | integer()]
2750 RestData = erlang:iovec()
2751 SelectInfo = select_info()
2752 Reason = posix() | closed | invalid()
2753 Sends a message on a socket, but returns a select continuation
2755 if the data could not be sent immediately.
2756 The same as infinity time-out sendmsg/2,3 but if the data is
2758 not immediately accepted by the platform network layer, the
2759 function returns {select, SelectInfo}, and the caller will then
2760 receive a select message, {'$socket', Socket, select, Selec‐
2761 tHandle} ( with the SelectHandle that was contained in the Se‐
2762 lectInfo ) when there is room for more data. A subsequent call
2763 to sendmsg/2-4 will then send the data.
2764 If SelectHandle, is a select_handle(), that term will be con‐
2766 tained in a returned SelectInfo and the corresponding select
2767 message. The SelectHandle is presumed to be unique to this call.
2768 If SelectHandle is nowait, and a SelectInfo is returned, it will
2770 contain a select_handle() generated by the call.
2771 If some of the data was sent, the function will return {ok,
2773 {RestData, SelectInfo}, which can only happen for a socket of
2774 type stream. If the caller does not want to wait to send the
2775 rest of the data, it should immediately cancel the operation
2776 with cancel/2.
2777 sendmsg(Socket, Data, Cont) ->
2779 ok |
2780 {ok, RestData} |
2781 {error, Reason} |
2782 {error, {Reason, RestData}}
2783 sendmsg(Socket, Data, Cont, Timeout :: infinity) ->
2785 ok |
2786 {ok, RestData} |
2787 {error, Reason} |
2788 {error, {Reason, RestData}}
2789 sendmsg(Socket, Data, Cont, Timeout :: integer() >= 0) ->
2791 ok |
2792 {ok, RestData} |
2793 {error, Reason | timeout} |
2794 {error, {Reason | timeout, RestData}}
2795 sendmsg(Socket, Data, Cont, SelectHandle :: nowait) ->
2797 ok |
2798 {ok, RestData} |
2799 {select, SelectInfo} |
2800 {select, {SelectInfo, RestData}} |
2801 {error, Reason} |
2802 {error, {Reason, RestData}}
2803 sendmsg(Socket, Data, Cont, SelectHandle :: select_handle()) ->
2805 ok |
2806 {ok, RestData} |
2807 {select, SelectInfo} |
2808 {select, {SelectInfo, RestData}} |
2809 {error, Reason} |
2810 {error, {Reason, RestData}}
2811 Types:
2813 Socket = socket()
2815 Data = msg_send() | erlang:iovec()
2816 Cont = select_info()
2817 RestData = erlang:iovec()
2818 SelectInfo = select_info()
2819 Reason = posix() | closed | invalid()
2820 Continues sending a message data on a socket, where the send op‐
2822 eration was initiated by sendmsg/3,4 that returned a SelectInfo
2823 continuation. Otherwise like infinite time-out sendmsg/2,3,4 ,
2824 limited time-out sendmsg/3,4 or nowait sendmsg/3,4 respec‐
2825 tively.
2826 Cont is the SelectInfo that was returned from the previous
2828 sendmsg() call.
2829 The return value indicates the result from the platform's net‐
2831 work layer. See send/2,3,4 and nowait sendmsg/3,4.
2832 sendto(Socket, Data, Dest) ->
2834 ok |
2835 {ok, RestData} |
2836 {error, Reason} |
2837 {error, {Reason, RestData}}
2838 sendto(Socket, Data, Dest, Flags) ->
2840 ok |
2841 {ok, RestData} |
2842 {error, Reason} |
2843 {error, {Reason, RestData}}
2844 sendto(Socket, Data, Dest, Timeout :: infinity) ->
2846 ok |
2847 {ok, RestData} |
2848 {error, Reason} |
2849 {error, {Reason, RestData}}
2850 sendto(Socket, Data, Dest, Flags, Timeout :: infinity) ->
2852 ok |
2853 {ok, RestData} |
2854 {error, Reason} |
2855 {error, {Reason, RestData}}
2856 Types:
2858 Socket = socket()
2860 Data = iodata()
2861 Dest = sockaddr()
2862 Flags = [msg_flag() | integer()]
2863 RestData = binary()
2864 Reason = posix() | closed | invalid()
2865 Sends data on a socket, to the specified destination, waiting
2867 for it to be sent.
2868 This call will not return until the data has been accepted by
2870 the platform's network layer, or it reports an error.
2871 If this call is used on a connection mode socket or on a con‐
2873 nected socket, the platforms's network layer may return an error
2874 or ignore the destination address.
2875 The message Flags may be symbolic msg_flag()s and/or integer()s,
2877 matching the platform's appropriate header files. The values of
2878 all symbolic flags and integers are or:ed together.
2879 The return value indicates the result from the platform's net‐
2881 work layer. See send/2,3,4.
2882 sendto(Socket, Data, Dest, Timeout :: integer() >= 0) ->
2884 ok |
2885 {ok, RestData} |
2886 {error, Reason | timeout} |
2887 {error, {Reason | timeout, RestData}}
2888 sendto(Socket, Data, Dest, Flags, Timeout :: integer() >= 0) ->
2890 ok |
2891 {ok, RestData} |
2892 {error, Reason | timeout} |
2893 {error, {Reason | timeout, RestData}}
2894 Types:
2896 Socket = socket()
2898 Data = iodata()
2899 Dest = sockaddr()
2900 Flags = [msg_flag() | integer()]
2901 RestData = binary()
2902 Reason = posix() | closed | invalid()
2903 Sends data on a socket, waiting at most Timeout milliseconds for
2905 it to be sent.
2906 The same as infinite time-out sendto/3,4,5 but returns {error,
2908 timeout} or {error, {timeout, RestData}} after Timeout millisec‐
2909 onds, if no Data or only some of it was accepted by the plat‐
2910 form's network layer.
2911 sendto(Socket, Data, Dest, SelectHandle :: nowait) ->
2913 ok |
2914 {ok, RestData} |
2915 {select, SelectInfo} |
2916 {select, {SelectInfo, RestData}} |
2917 {error, Reason}
2918 sendto(Socket, Data, Dest, SelectHandle :: select_handle()) ->
2920 ok |
2921 {ok, RestData} |
2922 {select, SelectInfo} |
2923 {select, {SelectInfo, RestData}} |
2924 {error, Reason}
2925 sendto(Socket, Data, Dest, Flags, SelectHandle :: nowait) ->
2927 ok |
2928 {ok, RestData} |
2929 {select, SelectInfo} |
2930 {select, {SelectInfo, RestData}} |
2931 {error, Reason}
2932 sendto(Socket, Data, Dest, Flags, SelectHandle :: select_handle()) ->
2934 ok |
2935 {ok, RestData} |
2936 {select, SelectInfo} |
2937 {select, {SelectInfo, RestData}} |
2938 {error, Reason}
2939 Types:
2941 Socket = socket()
2943 Data = iodata()
2944 Dest = sockaddr()
2945 Flags = [msg_flag() | integer()]
2946 RestData = binary()
2947 SelectInfo = select_info()
2948 Reason = posix() | closed | invalid()
2949 Sends data on a socket, but returns a select continuation if the
2951 data could not be sent immediately.
2952 The same as infinity time-out sendto/3,4 but if the data is not
2954 immediately accepted by the platform network layer, the function
2955 returns {select, SelectInfo}, and the caller will then receive a
2956 select message, {'$socket', Socket, select, SelectHandle} ( with
2957 the SelectHandle that was contained in the SelectInfo ) when
2958 there is room for more data. A subsequent call to sendto/3-5
2959 will then send the data.
2960 If SelectHandle is a select_handle(), that term will be con‐
2962 tained in a returned SelectInfo and the corresponding select
2963 message. The SelectHandle is presumed to be unique to this call.
2964 If SelectHandle is nowait, and a SelectInfo is returned, it will
2966 contain a select_handle() generated by the call.
2967 If some of the data was sent, the function will return {ok,
2969 {RestData, SelectInfo}, which can only happen for a socket of
2970 type stream. If the caller does not want to wait to send the
2971 rest of the data, it should immediately cancel the operation
2972 with cancel/2.
2973 sendto(Socket, Data, Cont) ->
2975 ok |
2976 {ok, RestData} |
2977 {error, Reason} |
2978 {error, {Reason, RestData}}
2979 sendto(Socket, Data, Cont, Timeout :: infinity) ->
2981 ok |
2982 {ok, RestData} |
2983 {error, Reason} |
2984 {error, {Reason, RestData}}
2985 sendto(Socket, Data, Cont, Timeout :: integer() >= 0) ->
2987 ok |
2988 {ok, RestData} |
2989 {error, Reason | timeout} |
2990 {error, {Reason | timeout, RestData}}
2991 sendto(Socket, Data, Cont, SelectHandle :: nowait) ->
2993 ok |
2994 {ok, RestData} |
2995 {select, SelectInfo} |
2996 {select, {SelectInfo, RestData}} |
2997 {error, Reason}
2998 sendto(Socket, Data, Cont, SelectHandle :: select_handle()) ->
3000 ok |
3001 {ok, RestData} |
3002 {select, SelectInfo} |
3003 {select, {SelectInfo, RestData}} |
3004 {error, Reason}
3005 Types:
3007 Socket = socket()
3009 Data = iodata()
3010 Cont = select_info()
3011 RestData = binary()
3012 SelectInfo = select_info()
3013 Reason = posix() | closed | invalid()
3014 Continues sending data on a socket, where the send operation was
3016 initiated by sendto/4,5 that returned a SelectInfo continuation.
3017 Otherwise like infinite time-out sendto/3,4,5 , limited time-
3018 out sendto/4,5 or nowait sendto/4,5 respectively.
3019 Cont is the SelectInfo that was returned from the previous
3021 sendto() call.
3022 If Data is not a binary(), it will be copied into one, again.
3024 The return value indicates the result from the platform's net‐
3026 work layer. See send/2,3,4 and nowait sendto/4,5.
3027 sendfile(Socket, FileHandle, Offset, Count, Timeout :: infinity) ->
3029 {ok, BytesSent} |
3030 {error, Reason} |
3031 {error, {Reason, BytesSent}}
3032 Types:
3034 Socket = socket()
3036 FileHandle = file:fd()
3037 Offset = integer()
3038 Count = BytesSent = integer() >= 0
3039 Reason = posix() | closed | invalid()
3040 Sends file data on a socket, to the specified destination, wait‐
3042 ing for it to be sent ("infinite" time-out).
3043 The FileHandle must refer to an open raw file as described in
3045 file:open/2.
3046 This call will not return until the data has been accepted by
3048 the platform's network layer, or it reports an error.
3049 The Offset argument is the file offset to start reading from.
3051 The default value is 0.
3052 The Count argument is the number of bytes to transfer from File‐
3054 Handle to Socket. If Count =:= 0 (the default) the transfer
3055 stops at the end of file.
3056 The return value indicates the result from the platform's net‐
3058 work layer:
3059 {ok, BytesSent}:
3061 The transfer completed successfully after BytesSent bytes of
3062 data.
3063 {error, Reason}:
3065 An error has been reported and no data has been transferred.
3066 The posix() Reasons are from the platform's network layer.
3067 closed means that this socket library knows that the socket
3068 is closed, and invalid() means that something about an argu‐
3069 ment is invalid.
3070 {error, {Reason, BytesSent}} :
3072 An error has been reported but before that some data was
3073 transferred. See {error, Reason} and {ok, BytesSent} above.
3074 sendfile(Socket, FileHandle, Offset, Count,
3076 Timeout :: integer() >= 0) ->
3077 {ok, BytesSent} |
3078 {error, Reason | timeout} |
3079 {error, {Reason | timeout, BytesSent}}
3080 Types:
3082 Socket = socket()
3084 FileHandle = file:fd()
3085 Offset = integer()
3086 Count = BytesSent = integer() >= 0
3087 Reason = posix() | closed | invalid()
3088 Sends file data on a socket, waiting at most Timeout millisec‐
3090 onds for it to be sent (limited time-out).
3091 The same as "infinite" time-out sendfile/5 but returns {error,
3093 timeout} or {error, {timeout, BytesSent}} after Timeout mil‐
3094 liseconds, if not all file data was transferred by the plat‐
3095 form's network layer.
3096 sendfile(Socket, FileHandle, Offset, Count,
3098 SelectHandle :: nowait) ->
3099 {ok, BytesSent} |
3100 {select, SelectInfo} |
3101 {select, {SelectInfo, BytesSent}} |
3102 {error, Reason}
3103 sendfile(Socket, FileHandle, Offset, Count,
3105 SelectHandle :: select_handle()) ->
3106 {ok, BytesSent} |
3107 {select, SelectInfo} |
3108 {select, {SelectInfo, BytesSent}} |
3109 {error, Reason}
3110 Types:
3112 Socket = socket()
3114 FileHandle = file:fd()
3115 Offset = integer()
3116 Count = BytesSent = integer() >= 0
3117 SelectInfo = select_info()
3118 Reason = posix() | closed | invalid()
3119 Sends file data on a socket, but returns a select continuation
3121 if the data could not be sent immediately (nowait).
3122 The same as "infinite" time-out sendfile/5 but if the data is
3124 not immediately accepted by the platform network layer, the
3125 function returns {select, SelectInfo}, and the caller will then
3126 receive a select message, {'$socket', Socket, select, Selec‐
3127 tHandle} ( with the SelectHandle that was contained in the Se‐
3128 lectInfo ) when there is room for more data. Then a call to
3129 sendfile/3 with SelectInfo as the second argument will continue
3130 the data transfer.
3131 If SelectHandle is a select_handle(), that term will be con‐
3133 tained in a returned SelectInfo and the corresponding select
3134 message. The SelectHandle is presumed to be unique to this call.
3135 If SelectHandle is nowait, and a SelectInfo is returned, it will
3137 contain a select_handle() generated by the call.
3138 If some file data was sent, the function will return {ok,
3140 {BytesSent, SelectInfo}. If the caller does not want to wait to
3141 send the rest of the data, it should immediately cancel the op‐
3142 eration with cancel/2.
3143 sendfile(Socket, Cont, Offset, Count, Timeout :: infinity) ->
3145 {ok, BytesSent} |
3146 {error, Reason} |
3147 {error, {Reason, BytesSent}}
3148 sendfile(Socket, Cont, Offset, Count,
3150 Timeout :: integer() >= 0) ->
3151 {ok, BytesSent} |
3152 {error, Reason | timeout} |
3153 {error, {Reason | timeout, BytesSent}}
3154 sendfile(Socket, Cont, Offset, Count, SelectHandle :: nowait) ->
3156 {ok, BytesSent} |
3157 {select, SelectInfo} |
3158 {select, {SelectInfo, BytesSent}} |
3159 {error, Reason}
3160 sendfile(Socket, Cont, Offset, Count,
3162 SelectHandle :: select_handle()) ->
3163 {ok, BytesSent} |
3164 {select, SelectInfo} |
3165 {select, {SelectInfo, BytesSent}} |
3166 {error, Reason}
3167 Types:
3169 Socket = socket()
3171 Cont = select_info()
3172 Offset = integer()
3173 Count = BytesSent = integer() >= 0
3174 SelectInfo = select_info()
3175 Reason = posix() | closed | invalid()
3176 Continues sending file data on a socket, where the send opera‐
3178 tion was initiated by sendfile/3,5 that returned a SelectInfo
3179 continuation. Otherwise like "infinite" time-out sendfile/5 ,
3180 limited time-out sendfile/5 or nowait sendfile/5 respectively.
3181 Cont is the SelectInfo that was returned from the previous send‐
3183 file() call.
3184 The return value indicates the result from the platform's net‐
3186 work layer. See "infinite" time-out sendfile/5.
3187 sendfile(Socket, FileHandle, Offset, Count) -> Result
3189 Types:
3191 Socket = socket()
3193 FileHandle = file:fd()
3194 Offset = integer()
3195 Count = integer() >= 0
3196 The same as sendfile(Socket, FileHandle, Offset, Count, infin‐
3198 ity), that is: send the file data at Offset and Count to the
3199 socket, without time-out other than from the platform's network
3200 stack.
3201 sendfile(Socket, FileHandle, Timeout) -> Result
3203 Types:
3205 Socket = socket()
3207 FileHandle = file:fd()
3208 Timeout = timeout() | 'nowait' | select_handle()
3209 Depending on the Timeout argument; the same as sendfile(Socket,
3211 FileHandle, 0, 0, infinity), sendfile(Socket, FileHandle, 0,
3212 0, Timeout), or sendfile(Socket, FileHandle, 0, 0, Selec‐
3213 tHandle), that is: send all data in the file to the socket,
3214 with the given Timeout.
3215 sendfile(Socket, FileHandle) -> Result
3217 Types:
3219 Socket = socket()
3221 FileHandle = file:fd()
3222 The same as sendfile(Socket, FileHandle, 0, 0, infinity), that
3224 is: send all data in the file to the socket, without time-out
3225 other than from the platform's network stack.
3226 setopt(Socket :: socket(),
3228 SocketOption :: {Level :: otp, Opt :: otp_socket_option()},
3229 Value :: term()) ->
3230 ok | {error, invalid() | closed}
3231 Sets a socket option in the protocol level otp, which is this
3233 implementation's level above the OS protocol layers.
3234 See the type otp_socket_option() for a description of the op‐
3236 tions on this level.
3237 setopt(Socket :: socket(),
3239 SocketOption :: socket_option(),
3240 Value :: term()) ->
3241 ok | {error, posix() | invalid() | closed}
3242 Set a socket option in one of the OS's protocol levels. See the
3244 type socket_option() for which options that this implementation
3245 knows about, how they are related to option names in the OS, and
3246 if there are known peculiarities with any of them.
3247 What options are valid depends on what kind of socket it is (do‐
3249 main(), type() and protocol()).
3250 See the socket options chapter of the users guide for more
3252 info.
3253 Note:
3255 Not all options are valid, nor possible to set, on all plat‐
3256 forms. That is, even if "we" support an option; it does not mean
3257 that the underlying OS does.
3258 setopt(Socket, Level, Opt, Value) -> ok | {error, Reason}
3261 Types:
3263 Socket = socket()
3265 Value = term()
3266 Reason = inet:posix() | invalid() | closed
3267 Backwards compatibility function.
3269 The same as setopt(Socket, {Level, Opt}, Value)
3271 setopt_native(Socket :: socket(),
3273 SocketOption ::
3274 socket_option() |
3275 {Level :: level() | (NativeLevel :: integer()),
3276 NativeOpt :: integer()},
3277 Value :: native_value()) ->
3278 ok | {error, posix() | invalid() | closed}
3279 Sets a socket option that may be unknown to our implementation,
3281 or that has a type not compatible with our implementation, that
3282 is; in "native mode".
3283 If Value is an integer() it will be used as a C type (int), if
3285 it is a boolean() it will be used as a C type (int) with the C
3286 implementations values for false or true, and if it is a bi‐
3287 nary() its content and size will be used as the option value.
3288 The socket option may be specified with an ordinary socket_op‐
3290 tion() tuple, with a known Level = level() and an integer Na‐
3291 tiveOpt, or with both an integer NativeLevel and NativeOpt.
3292 What options are valid depends on what kind of socket it is (do‐
3294 main(), type() and protocol()).
3295 The integer values for NativeLevel and NativeOpt as well as the
3297 encoding of Value has to be deduced from the header files for
3298 the running system.
3299 shutdown(Socket, How) -> ok | {error, Reason}
3301 Types:
3303 Socket = socket()
3305 How = read | write | read_write
3306 Reason = posix() | closed
3307 Shut down all or part of a full-duplex connection.
3309 sockname(Socket) -> {ok, SockAddr} | {error, Reason}
3311 Types:
3313 Socket = socket()
3315 SockAddr = sockaddr_recv()
3316 Reason = posix() | closed
3317 Returns the current address to which the socket is bound.
3319 supports() ->
3321 [{Key1 :: term(),
3322 boolean() |
3323 [{Key2 :: term(),
3324 boolean() | [{Key3 :: term(), boolean()}]}]}]
3325 supports(Key1 :: term()) ->
3327 [{Key2 :: term(),
3328 boolean() | [{Key3 :: term(), boolean()}]}]
3329 supports(Key1 :: term(), Key2 :: term()) ->
3331 [{Key3 :: term(), boolean()}]
3332 These functions function retrieves information about what the
3334 platform supports, such which platform features or which socket
3335 options, are supported.
3336 For keys other than the known the empty list is returned, Note
3338 that in a future version or on a different platform there might
3339 be more supported items.
3340 supports():
3342 Returns a list of {Key1, supports(Key1)} tuples for every
3343 Key1 described in supports/1 and {Key1, boolean()} tuples
3344 for each of the following keys:
3345 sctp:
3347 SCTP support
3348 ipv6:
3350 IPv6 support
3351 local:
3353 Unix Domain sockets support (AF_UNIX | AF_LOCAL)
3354 netns:
3356 Network Namespaces support (Linux, setns(2))
3357 sendfile:
3359 Sendfile support (sendfile(2))
3360 supports(msg_flags = Key1):
3362 Returns a list of {Flag, boolean()} tuples for every Flag in
3363 msg_flag() with the boolean() indicating if the flag is sup‐
3364 ported on this platform.
3365 supports(protocols = Key1):
3367 Returns a list of {Name :: atom(), boolean()} tuples for ev‐
3368 ery Name in protocol() with the boolean() indicating if the
3369 protocol is supported on this platform.
3370 supports(options = Key1):
3372 Returns a list of {SocketOption, boolean()} tuples for every
3373 SocketOption in socket_option() with the boolean() indicat‐
3374 ing if the socket option is supported on this platform.
3375 supports(options = Key1, Key2) :
3377 For a Key2 in level() returns a list of {Opt, boolean()} tu‐
3378 ples for all known socket options Opt on that Level =:=
3379 Key2, and the boolean() indicating if the socket option is
3380 supported on this platform. See setopt/3 and getopt/2.
3381 use_registry(D :: boolean()) -> ok
3383 Globally change if the socket registry is to be used or not.
3385 Note that its still possible to override this explicitly when
3386 creating an individual sockets, see open/2 or open/4 for more
3387 info (use the Extra argument).
3388 which_sockets() -> [socket()]
3390 which_sockets(FilterRule) -> [socket()]
3392 Types:
3394 FilterRule =
3396 inet | inet6 | local | stream | dgram | seqpacket | sctp
3397 |
3398 tcp | udp |
3399 pid() |
3400 fun((socket_info()) -> boolean())
3401 Returns a list of all sockets, according to the filter rule.
3403 There are several pre-made filter rule(s) and one general:
3405 inet | inet6:
3407 Selection based on the domain of the socket.
3408 Only a subset is valid.
3409 stream | dgram | seqpacket:
3411 Selection based on the type of the socket.
3412 Only a subset is valid.
3413 sctp | tcp | udp:
3415 Selection based on the protocol of the socket.
3416 Only a subset is valid.
3417 pid():
3419 Selection base on which sockets has this pid as Controlling
3420 Process.
3421 fun((socket_info()) -> boolean()):
3423 The general filter rule.
3424 A fun that takes the socket info and returns a boolean()
3425 (true if the socket could be included and false if should
3426 not).
3427
3429 client(SAddr, SPort) ->
3430 {ok, Sock} = socket:open(inet, stream, tcp),
3431 ok = socket:connect(Sock, #{family => inet,
3432 addr => SAddr,
3433 port => SPort}),
3434 Msg = <<"hello">>,
3435 ok = socket:send(Sock, Msg),
3436 ok = socket:shutdown(Sock, write),
3437 {ok, Msg} = socket:recv(Sock),
3438 ok = socket:close(Sock).
3439 server(Addr, Port) ->
3441 {ok, LSock} = socket:open(inet, stream, tcp),
3442 ok = socket:bind(LSock, #{family => inet,
3443 port => Port,
3444 addr => Addr}),
3445 ok = socket:listen(LSock),
3446 {ok, Sock} = socket:accept(LSock),
3447 {ok, Msg} = socket:recv(Sock),
3448 ok = socket:send(Sock, Msg),
3449 ok = socket:close(Sock),
3450 ok = socket:close(LSock).
3451Ericsson AB kernel 8.5.4.2 socket(3)