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 accept(ListenSocket, Timeout :: nowait) ->
1173 {ok, Socket} | {select, SelectInfo} | {error, Reason}
1174 accept(ListenSocket, SelectHandle :: select_handle()) ->
1176 {ok, Socket} | {select, SelectInfo} | {error, Reason}
1177 Types:
1179 ListenSocket = Socket = socket()
1181 SelectInfo = select_info()
1182 Reason = posix() | closed | invalid()
1183 The same as accept/1 but returns promptly.
1185 When there is no pending connection to return, the function will
1187 return {select, SelectInfo}, and the caller will later receive a
1188 select message, {'$socket', Socket, select, SelectHandle} ( with
1189 the SelectHandle contained in the SelectInfo ) when a client
1190 connects. A subsequent call to accept/1,2 will then return the
1191 socket.
1192 If the time-out argument is SelectHandle, that term will be con‐
1194 tained in a returned SelectInfo and the corresponding select
1195 message. The SelectHandle is presumed to be unique to this call.
1196 If the time-out argument is nowait, and a SelectInfo is re‐
1198 turned, it will contain a select_handle() generated by the call.
1199 If the caller doesn't want to wait for a connection, it must im‐
1201 mediately call cancel/2 to cancel the operation.
1202 bind(Socket, Addr) -> ok | {error, Reason}
1204 Types:
1206 Socket = socket()
1208 Addr = sockaddr() | any | broadcast | loopback
1209 Reason = posix() | closed | invalid()
1210 Bind a name to a socket.
1212 When a socket is created (with open), it has no address assigned
1214 to it. bind assigns the address specified by the Addr argument.
1215 The rules used for name binding vary between domains.
1217 If you bind a socket to an address in for example the 'inet' or
1219 'inet6' address families, with an ephemeral port number (0), and
1220 want to know which port that was chosen, you can find out using
1221 something like: {ok, #{port := Port}} = socket:sockname(Socket)
1222 cancel(Socket, SelectInfo) -> ok | {error, Reason}
1224 Types:
1226 Socket = socket()
1228 SelectInfo = select_info()
1229 Reason = closed | invalid()
1230 Cancel an asynchronous request.
1232 Call this function in order to cancel a previous asynchronous
1234 call to, e.g. recv/3.
1235 An ongoing asynchronous operation blocks the socket until the
1237 operation has been finished in good order, or until it has been
1238 cancelled by this function.
1239 Any other process that tries an operation of the same basic type
1241 (accept / send / recv) will be enqueued and notified with the
1242 regular select mechanism for asynchronous operations when the
1243 current operation and all enqueued before it has been completed.
1244 If SelectInfo does not match an operation in progress for the
1246 calling process, this function returns {error, {invalid, Select‐
1247 Info}}.
1248 close(Socket) -> ok | {error, Reason}
1250 Types:
1252 Socket = socket()
1254 Reason = posix() | closed | timeout
1255 Closes the socket.
1257 Note:
1259 Note that for e.g. protocol = tcp, most implementations doing a
1260 close does not guarantee that any data sent is delivered to the
1261 recipient before the close is detected at the remote side.
1262 One way to handle this is to use the shutdown function
1264 (socket:shutdown(Socket, write)) to signal that no more data is
1265 to be sent and then wait for the read side of the socket to be
1266 closed.
1267 connect(Socket, SockAddr) -> ok | {error, Reason}
1270 connect(Socket, SockAddr, Timeout :: infinity) ->
1272 ok | {error, Reason}
1273 Types:
1275 Socket = socket()
1277 SockAddr = sockaddr()
1278 Reason = posix() | closed | invalid() | already
1279 This function connects the socket to the address specified by
1281 the SockAddr argument, and returns when the connection has been
1282 established or failed.
1283 If a connection attempt is already in progress (by another
1285 process), {error, already} is returned.
1286 connect(Socket, SockAddr, Timeout :: integer() >= 0) ->
1288 ok | {error, Reason}
1289 Types:
1291 Socket = socket()
1293 SockAddr = sockaddr()
1294 Reason = posix() | closed | invalid() | already | timeout
1295 The same as connect/2 but returns {error, timeout} if no connec‐
1297 tion has been established after Timeout milliseconds.
1298 Note:
1300 Note that when this call has returned {error, timeout} the con‐
1301 nection state of the socket is uncertain since the platform's
1302 network stack may complete the connection at any time, up to
1303 some platform specific time-out.
1304 Repeating a connection attempt towards the same address would be
1306 ok, but towards a different address could end up with a connec‐
1307 tion to either address.
1308 The safe play would be to close the socket and start over.
1310 Also note that all this applies to cancelling a connect call
1312 with a no-wait time-out described below.
1313 connect(Socket, SockAddr, Timeout :: nowait) ->
1316 ok | {select, SelectInfo} | {error, Reason}
1317 connect(Socket, SockAddr, SelectHandle :: select_handle()) ->
1319 ok | {select, SelectInfo} | {error, Reason}
1320 Types:
1322 Socket = socket()
1324 SockAddr = sockaddr()
1325 SelectInfo = select_info()
1326 Reason = posix() | closed | invalid() | already
1327 The same as connect/2 but returns promptly.
1329 If it is not possible to immediately establish a connection, the
1331 function will return {select, SelectInfo}, and the caller will
1332 later receive a select message, {'$socket', Socket, select, Se‐
1333 lectHandle} ( with the SelectHandle contained in the SelectInfo
1334 ) when the connection has been completed or failed. A subsequent
1335 call to connect/1 will then finalize the connection and return
1336 the result.
1337 If the time-out argument is SelectHandle, that term will be con‐
1339 tained in a returned SelectInfo and the corresponding select
1340 message. The SelectHandle is presumed to be unique to this call.
1341 If the time-out argument is nowait, and a SelectInfo is re‐
1343 turned, it will contain a select_handle() generated by the call.
1344 If the caller doesn't want to wait for the connection to com‐
1346 plete, it must immediately call cancel/2 to cancel the opera‐
1347 tion.
1348 connect(Socket) -> ok | {error, Reason}
1350 Types:
1352 Socket = socket()
1354 Reason = posix() | closed | invalid()
1355 This function finalizes a connection setup on a socket, after
1357 calling connect(_, _, nowait | select_handle()) that returned
1358 {select, SelectInfo}, and receiving the select message
1359 {'$socket', Socket, select, SelectHandle}, and returns whether
1360 the connection setup was successful or not.
1361 Instead of calling this function, for backwards compatibility,
1363 it is allowed to call connect/2,3, but that incurs more overhead
1364 since the connect address and time-out are processed in vain.
1365 cancel_monitor(MRef) -> boolean()
1367 Types:
1369 MRef = reference()
1371 If MRef is a reference that the calling process obtained by
1373 calling monitor/1, this monitor is turned off. If the monitoring
1374 is already turned off, nothing happens.
1375 The returned value is one of the following:
1377 true:
1379 The monitor was found and removed. In this case, no 'DOWN'
1380 message corresponding to this monitor has been delivered and
1381 will not be delivered.
1382 false:
1384 The monitor was not found and could not be removed. This
1385 probably because a 'DOWN' message corresponding to this mon‐
1386 itor has already been placed in the caller message queue.
1387 Failure: It is an error if MRef refers to a monitor started by
1389 another process.
1390 getopt(X1 :: socket(),
1392 SocketOption :: {Level :: otp, Opt :: otp_socket_option()}) ->
1393 {ok, Value :: term()} | {error, invalid() | closed}
1394 Gets a socket option from the protocol level otp, which is this
1396 implementation's level above the OS protocol layers.
1397 See the type otp_socket_option() for a description of the op‐
1399 tions on this level.
1400 getopt(X1 :: socket(), SocketOption :: socket_option()) ->
1402 {ok, Value :: term()} |
1403 {error, posix() | invalid() | closed}
1404 Gets a socket option from one of the OS's protocol levels. See
1406 the type socket_option() for which options that this implementa‐
1407 tion knows about, how they are related to option names in the
1408 OS, and if there are known peculiarities with any of them.
1409 What options are valid depends on what kind of socket it is (do‐
1411 main(), type() and protocol()).
1412 See the socket options chapter of the users guide for more
1414 info.
1415 Note:
1417 Not all options are valid, nor possible to get, on all plat‐
1418 forms. That is, even if "we" support an option; it does not mean
1419 that the underlying OS does.
1420 getopt(Socket, Level, Opt) -> ok | {error, Reason}
1423 Types:
1425 Socket = socket()
1427 Reason = inet:posix() | invalid() | closed
1428 Backwards compatibility function.
1430 The same as getopt(Socket, {Level, Opt})
1432 getopt_native(X1 :: socket(),
1434 SocketOption ::
1435 socket_option() |
1436 {Level :: level() | (NativeLevel :: integer()),
1437 NativeOpt :: integer()},
1438 ValueType :: integer) ->
1439 {ok, Value :: integer()} |
1440 {error, posix() | invalid() | closed}
1441 getopt_native(X1 :: socket(),
1443 SocketOption ::
1444 socket_option() |
1445 {Level :: level() | (NativeLevel :: integer()),
1446 NativeOpt :: integer()},
1447 ValueType :: boolean) ->
1448 {ok, Value :: boolean()} |
1449 {error, posix() | invalid() | closed}
1450 getopt_native(X1 :: socket(),
1452 SocketOption ::
1453 socket_option() |
1454 {Level :: level() | (NativeLevel :: integer()),
1455 NativeOpt :: integer()},
1456 ValueSize :: integer() >= 0) ->
1457 {ok, Value :: binary()} |
1458 {error, posix() | invalid() | closed}
1459 getopt_native(X1 :: socket(),
1461 SocketOption ::
1462 socket_option() |
1463 {Level :: level() | (NativeLevel :: integer()),
1464 NativeOpt :: integer()},
1465 ValueSpec :: binary()) ->
1466 {ok, Value :: binary()} |
1467 {error, posix() | invalid() | closed}
1468 Gets a socket option that may be unknown to our implementation,
1470 or that has a type not compatible with our implementation, that
1471 is; in "native mode".
1472 The socket option may be specified with an ordinary socket_op‐
1474 tion() tuple, with a known Level = level() and an integer Na‐
1475 tiveOpt, or with both an integer NativeLevel and NativeOpt.
1476 How to decode the option value has to be specified either with
1478 ValueType, by specifying the ValueSize for a binary() that will
1479 contain the fetched option value, or by specifying a binary()
1480 ValueSpec that will be copied to a buffer for the getsockopt()
1481 call to write the value in which will be returned as a new bi‐
1482 nary().
1483 If ValueType is integer a C type (int) will be fetched, if it is
1485 boolean a C type (int) will be fetched and converted into a
1486 boolean() according to the C implementation.
1487 What options are valid depends on what kind of socket it is (do‐
1489 main(), type() and protocol()).
1490 The integer values for NativeLevel and NativeOpt as well as the
1492 Value encoding has to be deduced from the header files for the
1493 running system.
1494 i() -> ok
1496 Print all sockets in table format in the erlang shell.
1498 i(InfoKeys) -> ok
1500 Types:
1502 InfoKeys = info_keys()
1504 Print all sockets in table format in the erlang shell. What in‐
1506 formation is included is defined by InfoKeys.
1507 i(Domain) -> ok
1509 Types:
1511 Domain = inet | inet6 | local
1513 Print a selection, based on domain, of the sockets in table for‐
1515 mat in the erlang shell.
1516 i(Proto) -> ok
1518 Types:
1520 Proto = sctp | tcp | udp
1522 Print a selection, based on protocol, of the sockets in table
1524 format in the erlang shell.
1525 i(Type) -> ok
1527 Types:
1529 Type = dgram | seqpacket | stream
1531 Print a selection, based on type, of the sockets in table format
1533 in the erlang shell.
1534 i(Domain, InfoKeys) -> ok
1536 Types:
1538 Domain = inet | inet6 | local
1540 InfoKeys = info_keys()
1541 Print a selection, based on domain, of the sockets in table for‐
1543 mat in the erlang shell. What information is included is defined
1544 by InfoKeys.
1545 i(Proto, InfoKeys) -> ok
1547 Types:
1549 Proto = sctp | tcp | udp
1551 InfoKeys = info_keys()
1552 Print a selection, based on domain, of the sockets in table for‐
1554 mat in the erlang shell. What information is included is defined
1555 by InfoKeys.
1556 i(Type, InfoKeys) -> ok
1558 Types:
1560 Type = dgram | seqpacket | stream
1562 InfoKeys = info_keys()
1563 Print a selection, based on type, of the sockets in table format
1565 in the erlang shell. What information is included is defined by
1566 InfoKeys.
1567 info() -> info()
1569 Get miscellaneous info about the socket library.
1571 The function returns a map with each info item as a key-value
1573 binding.
1574 Note:
1576 In order to ensure data integrity, mutex'es are taken when
1577 needed. So, do not call this function often.
1578 info(Socket) -> socket_info()
1581 Types:
1583 Socket = socket()
1585 Get miscellaneous info about the socket.
1587 The function returns a map with each info item as a key-value
1589 binding. It reflects the "current" state of the socket.
1590 Note:
1592 In order to ensure data integrity, mutex'es are taken when
1593 needed. So, do not call this function often.
1594 ioctl(Socket, GetRequest) -> {ok, IFConf} | {error, Reason}
1597 Types:
1599 Socket = socket()
1601 GetRequest = gifconf
1602 IFConf = [#{name := string, addr := sockaddr()}]
1603 Reason = posix() | closed
1604 Retrieve socket (device) parameters.
1606 ioctl(Socket, GetRequest, NameOrIndex) ->
1608 {ok, Result} | {error, Reason}
1609 Types:
1611 Socket = socket()
1613 GetRequest =
1614 gifname | gifindex | gifaddr | gifdstaddr | gifbrdaddr |
1615 gifnetmask | gifhwaddr | gifmtu | giftxqlen | gifflags
1616 NameOrIndex = string() | integer()
1617 Result = term()
1618 Reason = posix() | closed
1619 Retrieve socket (device) parameters. This function retrieves a
1621 specific parameter, according to GetRequest argument. The third
1622 argument is the (lookup) "key", identifying the interface (usu‐
1623 ally the name of the interface).
1624 gifname:
1626 Get the name of the interface with the specified index (in‐
1627 teger()).
1628 Result, name of the interface, is a string().
1630 gifindex:
1632 Get the index of the interface with the specified name.
1633 Result, interface index, is a integer().
1635 gifaddr:
1637 Get the address of the interface with the specified name.
1638 Result, address of the interface, is a socket:sockaddr().
1639 gifdstaddr:
1641 Get the destination address of the point-to-point interface
1642 with the specified name.
1643 Result, destination address of the interface, is a
1645 socket:sockaddr().
1646 gifbrdaddr:
1648 Get the droadcast address for the interface with the speci‐
1649 fied name.
1650 Result, broadcast address of the interface, is a
1652 socket:sockaddr().
1653 gifnetmask:
1655 Get the network mask for the interface with the specified
1656 name.
1657 Result, network mask of the interface, is a socket:sock‐
1659 addr().
1660 gifhwaddr:
1662 Get the hardware address for the interface with the speci‐
1663 fied name.
1664 Result, hardware address of the interface, is a socket:sock‐
1666 addr(). The family field contains the 'ARPHRD' device type
1667 (or an integer).
1668 gifmtu:
1670 Get the MTU (Maximum Transfer Unit) for the interface with
1671 the specified name.
1672 Result, MTU of the interface, is an integer().
1674 giftxqlen:
1676 Get the transmit queue length of the interface with the
1677 specified name.
1678 Result, transmit queue length of the interface, is an inte‐
1680 ger().
1681 gifflags:
1683 Get the active flag word of the interface with the specified
1684 name.
1685 Result, the active flag word of the interface, is an list of
1687 socket:ioctl_device_flag() | integer().
1688 ioctl(Socket, SetRequest, Name, Value) -> ok | {error, Reason}
1690 Types:
1692 Socket = socket()
1694 SetRequest =
1695 sifflags | sifaddr | sifdstaddr | sifbrdaddr | sifnetmask
1696 |
1697 sifhwaddr | gifmtu | siftxqlen
1698 Name = string()
1699 Value = term()
1700 Reason = posix() | closed
1701 Set socket (device) parameters. This function sets a specific
1703 parameter, according to SetRequest argument. The third argument
1704 is the "key", identifying the interface (usually the name of the
1705 interface), and the fourth is the "new" value.
1706 These are privileged operation's.
1708 sifflags:
1710 Set the the active flag word, #{Flag => boolean()}, of the
1711 interface with the specified name.
1712 Each flag to be changed, should be added to the value map,
1714 with the value 'true' if the flag (Flag) should be set and
1715 'false' if the flag should be reset.
1716 sifaddr:
1718 Set the address, sockaddr(), of the interface with the spec‐
1719 ified name.
1720 sifdstaddr:
1722 Set the destination address, sockaddr(), of a point-to-point
1723 interface with the specified name.
1724 sifbrdaddr:
1726 Set the broadcast address, sockaddr(), of the interface with
1727 the specified name.
1728 sifnetmask:
1730 Set the network mask, sockaddr(), of the interface with the
1731 specified name.
1732 sifmtu:
1734 Set the MTU (Maximum Transfer Unit), integer(), for the in‐
1735 terface with the specified name.
1736 siftxqlen:
1738 Set the transmit queue length, integer(), of the interface
1739 with the specified name.
1740 is_supported(Key1 :: term()) -> boolean()
1742 is_supported(Key1 :: term(), Key2 :: term()) -> boolean()
1744 This function retrieves information about what the platform sup‐
1746 ports, such as if SCTP is supported, or if a socket options are
1747 supported.
1748 For keys other than the known false is returned. Note that in a
1750 future version or on a different platform there might be more
1751 supported items.
1752 This functions returns a boolean corresponding to what sup‐
1754 ports/0-2 reports for the same Key1 (and Key2).
1755 listen(Socket) -> ok | {error, Reason}
1757 listen(Socket, Backlog) -> ok | {error, Reason}
1759 Types:
1761 Socket = socket()
1763 Backlog = integer()
1764 Reason = posix() | closed
1765 Listen for connections on a socket.
1767 monitor(Socket) -> reference()
1769 Types:
1771 Socket = socket()
1773 Start monitor the socket Socket.
1775 If the monitored socket does not exist or when the monitor is
1777 triggered, a 'DOWN' message is sent that has the following pat‐
1778 tern:
1779 {'DOWN', MonitorRef, socket, Object, Info}
1781 In the monitor message MonitorRef and Type are the same as de‐
1784 scribed earlier, and:
1785 Object:
1787 The monitored entity, socket, which triggered the event.
1788 Info:
1790 Either the termination reason of the socket or nosock
1791 (socket Socket did not exist at the time of monitor cre‐
1792 ation).
1793 Making several calls to socket:monitor/1 for the same Socket is
1795 not an error; it results in as many independent monitoring in‐
1796 stances.
1797 number_of() -> integer() >= 0
1799 Returns the number of active sockets.
1801 open(FD) -> {ok, Socket} | {error, Reason}
1803 open(FD, Opts) -> {ok, Socket} | {error, Reason}
1805 Types:
1807 FD = integer()
1809 Opts =
1810 #{domain => domain() | integer(),
1811 type => type() | integer(),
1812 protocol => default | protocol() | integer(),
1813 dup => boolean(),
1814 debug => boolean(),
1815 use_registry => boolean()}
1816 Socket = socket()
1817 Reason = posix() | domain | type | protocol
1818 Creates an endpoint (socket) for communication based on an al‐
1820 ready existing file descriptor. The function attempts to re‐
1821 trieve domain, type and protocol from the system. This is how‐
1822 ever not possible on all platforms, and they should then be
1823 specified in Opts.
1824 The Opts argument is intended for providing extra information
1826 for the open call:
1827 domain:
1829 Which protocol domain is the descriptor of. See also
1830 open/2,3,4.
1831 type:
1833 Which protocol type type is the descriptor of.
1834 See also open/2,3,4.
1836 protocol:
1838 Which protocol is the descriptor of. The atom default is
1839 equivalent to the integer protocol number 0 which means the
1840 default protocol for a given domain and type.
1841 If the protocol can not be retrieved from the platform for
1843 the socket, and protocol is not specified, the default pro‐
1844 tocol is used, which may or may not be correct.
1845 See also open/2,3,4.
1847 dup:
1849 Shall the provided descriptor be duplicated (dup) or not.
1850 Defaults to true.
1851 debug:
1853 Enable or disable debug during the open call.
1854 Defaults to false.
1855 use_registry>:
1857 Enable or disable use of the socket registry for this
1858 socket. This overrides the global value.
1859 Defaults to the global value, see use_registry/1.
1860 Note:
1862 This function should be used with care!
1863 On some platforms it is necessary to provide domain, type and
1865 protocol since they cannot be retrieved from the platform.
1866 open(Domain, Type) -> {ok, Socket} | {error, Reason}
1869 open(Domain, Type, Opts) -> {ok, Socket} | {error, Reason}
1871 Types:
1873 Domain = domain() | integer()
1875 Type = type() | integer()
1876 Opts = map()
1877 Socket = socket()
1878 Reason = posix() | protocol
1879 Creates an endpoint (socket) for communication.
1881 The same as open(Domain, Type, default) and open(Domain, Type,
1883 default, Opts) respectively.
1884 open(Domain, Type, Protocol) -> {ok, Socket} | {error, Reason}
1886 open(Domain, Type, Protocol, Opts) ->
1888 {ok, Socket} | {error, Reason}
1889 Types:
1891 Domain = domain() | integer()
1893 Type = type() | integer()
1894 Protocol = default | protocol() | integer()
1895 Opts =
1896 #{netns => string(),
1897 debug => boolean(),
1898 use_registry => boolean()}
1899 Socket = socket()
1900 Reason = posix() | protocol
1901 Creates an endpoint (socket) for communication.
1903 Domain and Type may be integer()s, as defined in the platform's
1905 header files. The same goes for Protocol as defined in the plat‐
1906 form's services(5) database. See also the OS man page for the
1907 library call socket(2).
1908 Note:
1910 For some combinations of Domain and Type the platform has got a
1911 default protocol that can be selected with Protocol = default,
1912 and the platform may allow or require selecting the default pro‐
1913 tocol, a specific protocol, or either.
1914 Examples:
1916 socket:open(inet, stream, tcp):
1918 It is common that for protocol domain and type inet,stream
1919 it is allowed to select the tcp protocol although that
1920 mostly is the default.
1921 socket:open(local, dgram):
1923 It is common that for the protocol domain local it is manda‐
1924 tory to not select a protocol, that is; to select the de‐
1925 fault protocol.
1926 The Opts argument is intended for "other" options. The supported
1929 option(s) are described below:
1930 netns: string():
1932 Used to set the network namespace during the open call. Only
1933 supported on the Linux platform.
1934 debug: boolean():
1936 Enable or disable debug during the open call.
1937 Defaults to false.
1938 use_registry: boolean():
1940 Enable or disable use of the socket registry for this
1941 socket. This overrides the global value.
1942 Defaults to the global value, see use_registry/1.
1943 peername(Socket) -> {ok, SockAddr} | {error, Reason}
1945 Types:
1947 Socket = socket()
1949 SockAddr = sockaddr_recv()
1950 Reason = posix() | closed
1951 Returns the address of the peer connected to the socket.
1953 recv(Socket) ->
1955 {ok, Data} | {error, Reason} | {error, {Reason, Data}}
1956 recv(Socket, Flags) ->
1958 {ok, Data} | {error, Reason} | {error, {Reason, Data}}
1959 recv(Socket, Length) ->
1961 {ok, Data} | {error, Reason} | {error, {Reason, Data}}
1962 recv(Socket, Flags, Timeout :: infinity) ->
1964 {ok, Data} | {error, Reason} | {error, {Reason, Data}}
1965 recv(Socket, Length, Flags) ->
1967 {ok, Data} | {error, Reason} | {error, {Reason, Data}}
1968 recv(Socket, Length, Timeout :: infinity) ->
1970 {ok, Data} | {error, Reason} | {error, {Reason, Data}}
1971 recv(Socket, Length, Flags, Timeout :: infinity) ->
1973 {ok, Data} | {error, Reason} | {error, {Reason, Data}}
1974 Types:
1976 Socket = socket()
1978 Length = integer() >= 0
1979 Flags = [msg_flag() | integer()]
1980 Data = binary()
1981 Reason = posix() | closed | invalid()
1982 Receives data from a socket, waiting for it to arrive.
1984 The argument Length specifies how many bytes to receive, with
1986 the special case 0 meaning "all available".
1987 For a socket of type stream this call will not return until all
1989 requested data can be delivered, or if "all available" data was
1990 requested when the first data chunk arrives.
1991 The message Flags may be symbolic msg_flag()s and/or integer()s,
1993 as in the platform's appropriate header files. The values of all
1994 symbolic flags and integers are or:ed together.
1995 When there is a socket error this function returns {error, Rea‐
1997 son}, or if some data arrived before the error; {error, {Reason,
1998 Data}}.
1999 recv(Socket, Flags, Timeout :: integer() >= 0) ->
2001 {ok, Data} | {error, Reason} | {error, {Reason, Data}}
2002 recv(Socket, Length, Timeout :: integer() >= 0) ->
2004 {ok, Data} | {error, Reason} | {error, {Reason, Data}}
2005 recv(Socket, Length, Flags, Timeout :: integer() >= 0) ->
2007 {ok, Data} | {error, Reason} | {error, {Reason, Data}}
2008 Types:
2010 Socket = socket()
2012 Length = integer() >= 0
2013 Flags = [msg_flag() | integer()]
2014 Data = binary()
2015 Reason = posix() | closed | invalid() | timeout
2016 Receives data from a socket, waiting at most Timeout millisec‐
2018 onds for it to arrive.
2019 The same as infinite time-out recv/1,2,3,4 but returns {error,
2021 timeout} or {error, {timeout, Data}} after Timeout milliseconds,
2022 if the requested data has not been delivered.
2023 recv(Socket, Flags, SelectHandle :: nowait) ->
2025 {ok, Data} |
2026 {select, SelectInfo} |
2027 {select, {SelectInfo, Data}} |
2028 {error, Reason} |
2029 {error, {Reason, Data}}
2030 recv(Socket, Flags, SelectHandle :: select_handle()) ->
2032 {ok, Data} |
2033 {select, SelectInfo} |
2034 {select, {SelectInfo, Data}} |
2035 {error, Reason} |
2036 {error, {Reason, Data}}
2037 recv(Socket, Length, SelectHandle :: nowait) ->
2039 {ok, Data} |
2040 {select, SelectInfo} |
2041 {select, {SelectInfo, Data}} |
2042 {error, Reason} |
2043 {error, {Reason, Data}}
2044 recv(Socket, Length, SelectHandle :: select_handle()) ->
2046 {ok, Data} |
2047 {select, SelectInfo} |
2048 {select, {SelectInfo, Data}} |
2049 {error, Reason} |
2050 {error, {Reason, Data}}
2051 recv(Socket, Length, Flags, SelectHandle :: nowait) ->
2053 {ok, Data} |
2054 {select, SelectInfo} |
2055 {select, {SelectInfo, Data}} |
2056 {error, Reason} |
2057 {error, {Reason, Data}}
2058 recv(Socket, Length, Flags, SelectHandle :: select_handle()) ->
2060 {ok, Data} |
2061 {select, SelectInfo} |
2062 {select, {SelectInfo, Data}} |
2063 {error, Reason} |
2064 {error, {Reason, Data}}
2065 Types:
2067 Socket = socket()
2069 Length = integer() >= 0
2070 Flags = [msg_flag() | integer()]
2071 Data = binary()
2072 SelectInfo = select_info()
2073 Reason = posix() | closed | invalid()
2074 Receives data from a socket, but returns a select continuation
2076 if the data could not be returned immediately.
2077 The same as infinite time-out recv/1,2,3,4 but if the data can‐
2079 not be delivered immediately, the function returns {select, Se‐
2080 lectInfo}, and the caller will then receive a select message,
2081 {'$socket', Socket, select, SelectHandle} ( with the Selec‐
2082 tHandle contained in the SelectInfo ) when data has arrived. A
2083 subsequent call to recv/1,2,3,4 will then return the data.
2084 If the time-out argument is SelectHandle, that term will be con‐
2086 tained in a returned SelectInfo and the corresponding select
2087 message. The SelectHandle is presumed to be unique to this call.
2088 If the time-out argument is nowait, and a SelectInfo is re‐
2090 turned, it will contain a select_handle() generated by the call.
2091 Note that for a socket of type stream, if Length > 0 and only
2093 part of that amount of data is available, the function will re‐
2094 turn {ok, {Data, SelectInfo with partial data. If the caller
2095 doesn't want to wait for more data, it must immediately call
2096 cancel/2 to cancel the operation.
2097 recvfrom(Socket) -> {ok, {Source, Data}} | {error, Reason}
2099 recvfrom(Socket, Flags) -> {ok, {Source, Data}} | {error, Reason}
2101 recvfrom(Socket, BufSz) -> {ok, {Source, Data}} | {error, Reason}
2103 recvfrom(Socket, Flags, Timeout :: infinity) ->
2105 {ok, {Source, Data}} | {error, Reason}
2106 recvfrom(Socket, BufSz, Flags) ->
2108 {ok, {Source, Data}} | {error, Reason}
2109 recvfrom(Socket, BufSz, Timeout :: infinity) ->
2111 {ok, {Source, Data}} | {error, Reason}
2112 recvfrom(Socket, BufSz, Flags, Timeout :: infinity) ->
2114 {ok, {Source, Data}} | {error, Reason}
2115 Types:
2117 Socket = socket()
2119 BufSz = integer() >= 0
2120 Flags = [msg_flag() | integer()]
2121 Source = sockaddr_recv()
2122 Data = binary()
2123 Reason = posix() | closed | invalid()
2124 Receive a message from a socket, waiting for it to arrive.
2126 The function returns when a message is received, or when there
2128 is a socket error. Argument BufSz specifies the number of bytes
2129 for the receive buffer. If the buffer size is too small, the
2130 message will be truncated.
2131 If BufSz is not specified or 0, a default buffer size is used,
2133 which can be set by socket:setopt(Socket, {otp,recvbuf}, BufSz).
2134 If it is impossible to know the appropriate buffer size, it may
2136 be possible to use the receive message flag peek. When this flag
2137 is used, the message is not "consumed" from the underlying buf‐
2138 fers, so another recvfrom/1,2,3,4 call is needed, possibly with
2139 an adjusted buffer size.
2140 The message Flags may be symbolic msg_flag()s and/or integer()s,
2142 as in the platform's appropriate header files. The values of all
2143 symbolic flags and integers are or:ed together.
2144 recvfrom(Socket, Flags, Timeout :: integer() >= 0) ->
2146 {ok, {Source, Data}} | {error, Reason}
2147 recvfrom(Socket, BufSz, Timeout :: integer() >= 0) ->
2149 {ok, {Source, Data}} | {error, Reason}
2150 recvfrom(Socket, BufSz, Flags, Timeout :: integer() >= 0) ->
2152 {ok, {Source, Data}} | {error, Reason}
2153 Types:
2155 Socket = socket()
2157 BufSz = integer() >= 0
2158 Flags = [msg_flag() | integer()]
2159 Source = sockaddr_recv()
2160 Data = binary()
2161 Reason = posix() | closed | invalid() | timeout
2162 Receives a message from a socket, waiting at most Timeout mil‐
2164 liseconds for it to arrive.
2165 The same as infinite time-out recvfrom/1,2,3,4 but returns {er‐
2167 ror, timeout} after Timeout milliseconds, if no message has been
2168 delivered.
2169 recvfrom(Socket, Flags, SelectHandle :: nowait) ->
2171 {ok, {Source, Data}} |
2172 {select, SelectInfo} |
2173 {error, Reason}
2174 recvfrom(Socket, Flags, SelectHandle :: select_handle()) ->
2176 {ok, {Source, Data}} |
2177 {select, SelectInfo} |
2178 {error, Reason}
2179 recvfrom(Socket, BufSz, SelectHandle :: nowait) ->
2181 {ok, {Source, Data}} |
2182 {select, SelectInfo} |
2183 {error, Reason}
2184 recvfrom(Socket, BufSz, SelectHandle :: select_handle()) ->
2186 {ok, {Source, Data}} |
2187 {select, SelectInfo} |
2188 {error, Reason}
2189 recvfrom(Socket, BufSz, Flags, SelectHandle :: nowait) ->
2191 {ok, {Source, Data}} |
2192 {select, SelectInfo} |
2193 {error, Reason}
2194 recvfrom(Socket, BufSz, Flags, SelectHandle :: select_handle()) ->
2196 {ok, {Source, Data}} |
2197 {select, SelectInfo} |
2198 {error, Reason}
2199 Types:
2201 Socket = socket()
2203 BufSz = integer() >= 0
2204 Flags = [msg_flag() | integer()]
2205 Source = sockaddr_recv()
2206 Data = binary()
2207 SelectInfo = select_info()
2208 Reason = posix() | closed | invalid()
2209 Receives a message from a socket, but returns a select continua‐
2211 tion if no message could be returned immediately.
2212 The same as infinite time-out recvfrom/1,2,3,4 but if no mes‐
2214 sage cannot delivered immediately, the function returns {select,
2215 SelectInfo}, and the caller will then receive a select message,
2216 {'$socket', Socket, select, SelectHandle} ( with the Selec‐
2217 tHandle contained in the SelectInfo ) when data has arrived. A
2218 subsequent call to recvfrom/1,2,3,4 will then return the mes‐
2219 sage.
2220 If the time-out argument is SelectHandle, that term will be con‐
2222 tained in a returned SelectInfo and the corresponding select
2223 message. The SelectHandle is presumed to be unique to this call.
2224 If the time-out argument is nowait, and a SelectInfo is re‐
2226 turned, it will contain a select_handle() generated by the call.
2227 If the caller doesn't want to wait for the data, it must immedi‐
2229 ately call cancel/2 to cancel the operation.
2230 recvmsg(Socket) -> {ok, Msg} | {error, Reason}
2232 recvmsg(Socket, Flags) -> {ok, Msg} | {error, Reason}
2234 recvmsg(Socket, Timeout :: infinity) ->
2236 {ok, Msg} | {error, Reason}
2237 recvmsg(Socket, Flags, Timeout :: infinity) ->
2239 {ok, Msg} | {error, Reason}
2240 recvmsg(Socket, BufSz, CtrlSz) -> {ok, Msg} | {error, Reason}
2242 recvmsg(Socket, BufSz, CtrlSz, Timeout :: infinity) ->
2244 {ok, Msg} | {error, Reason}
2245 recvmsg(Socket, BufSz, CtrlSz, Flags, Timeout :: infinity) ->
2247 {ok, Msg} | {error, Reason}
2248 Types:
2250 Socket = socket()
2252 BufSz = CtrlSz = integer() >= 0
2253 Flags = [msg_flag() | integer()]
2254 Msg = msg_recv()
2255 Reason = posix() | closed | invalid()
2256 Receive a message from a socket, waiting for it to arrive.
2258 The function returns when a message is received, or when there
2260 is a socket error. Arguments BufSz and CtrlSz specifies the num‐
2261 ber of bytes for the receive buffer and the control message buf‐
2262 fer. If the buffer size(s) is(are) too small, the message and/or
2263 control message list will be truncated.
2264 If BufSz is not specified or 0, a default buffer size is used,
2266 which can be set by socket:setopt(Socket, {otp,recvbuf}, BufSz).
2267 The same applies to CtrlSz and socket:setopt(Socket, {otp,recvc‐
2268 trlbuf}, CtrlSz).
2269 If it is impossible to know the appropriate buffer size, it may
2271 be possible to use the receive message flag peek. When this flag
2272 is used, the message is not "consumed" from the underlying buf‐
2273 fers, so another recvfrom/1,2,3,4,5 call is needed, possibly
2274 with an adjusted buffer size.
2275 The message Flags may be symbolic msg_flag()s and/or integer()s,
2277 as in the platform's appropriate header files. The values of all
2278 symbolic flags and integers are or:ed together.
2279 recvmsg(Socket, Timeout :: integer() >= 0) ->
2281 {ok, Msg} | {error, Reason}
2282 recvmsg(Socket, Flags, Timeout :: integer() >= 0) ->
2284 {ok, Msg} | {error, Reason}
2285 recvmsg(Socket, BufSz, CtrlSz, Timeout :: integer() >= 0) ->
2287 {ok, Msg} | {error, Reason}
2288 recvmsg(Socket, BufSz, CtrlSz, Flags,
2290 Timeout :: integer() >= 0) ->
2291 {ok, Msg} | {error, Reason}
2292 Types:
2294 Socket = socket()
2296 BufSz = CtrlSz = integer() >= 0
2297 Flags = [msg_flag() | integer()]
2298 Msg = msg_recv()
2299 Reason = posix() | closed | invalid() | timeout
2300 Receives a message from a socket, waiting at most Timeout mil‐
2302 liseconds for it to arrive.
2303 The same as recvmsg/1,2,3,4,5 but returns {error, timeout} after
2305 Timeout milliseconds, if no message has been delivered.
2306 recvmsg(Socket, Timeout :: nowait) ->
2308 {ok, Msg} | {select, SelectInfo} | {error, Reason}
2309 recvmsg(Socket, SelectHandle :: select_handle()) ->
2311 {ok, Msg} | {select, SelectInfo} | {error, Reason}
2312 recvmsg(Socket, Flags, Timeout :: nowait) ->
2314 {ok, Msg} | {select, SelectInfo} | {error, Reason}
2315 recvmsg(Socket, Flags, SelectHandle :: select_handle()) ->
2317 {ok, Msg} | {select, SelectInfo} | {error, Reason}
2318 recvmsg(Socket, BufSz, CtrlSz, SelectHandle :: nowait) ->
2320 {ok, Msg} | {select, SelectInfo} | {error, Reason}
2321 recvmsg(Socket, BufSz, CtrlSz, SelectHandle :: select_handle()) ->
2323 {ok, Msg} | {select, SelectInfo} | {error, Reason}
2324 recvmsg(Socket, BufSz, CtrlSz, Flags, SelectHandle :: nowait) ->
2326 {ok, Msg} | {select, SelectInfo} | {error, Reason}
2327 recvmsg(Socket, BufSz, CtrlSz, Flags,
2329 SelectHandle :: select_handle()) ->
2330 {ok, Msg} | {select, SelectInfo} | {error, Reason}
2331 Types:
2333 Socket = socket()
2335 BufSz = CtrlSz = integer() >= 0
2336 Flags = [msg_flag() | integer()]
2337 Msg = msg_recv()
2338 SelectInfo = select_info()
2339 Reason = posix() | closed | invalid()
2340 Receives a message from a socket, but returns a select continua‐
2342 tion if no message could be returned immediately.
2343 The same as infinite time-out recvfrom/1,2,3,4 but if no mes‐
2345 sage cannot delivered immediately, the function returns {select,
2346 SelectInfo}, and the caller will then receive a select message,
2347 {'$socket', Socket, select, SelectHandle} ( with the Selec‐
2348 tHandle contained in the SelectInfo ) when data has arrived. A
2349 subsequent call to recvmsg/1,2,3,4,5 will then return the data.
2350 If the time-out argument is SelectHandle, that term will be con‐
2352 tained in a returned SelectInfo and the corresponding select
2353 message. The SelectHandle is presumed to be unique to this call.
2354 If the time-out argument is nowait, and a SelectInfo is re‐
2356 turned, it will contain a select_handle() generated by the call.
2357 If the caller doesn't want to wait for the data, it must immedi‐
2359 ately call cancel/2 to cancel the operation.
2360 send(Socket, Data) ->
2362 ok |
2363 {ok, RestData} |
2364 {error, Reason} |
2365 {error, {Reason, RestData}}
2366 send(Socket, Data, Flags) ->
2368 ok |
2369 {ok, RestData} |
2370 {error, Reason} |
2371 {error, {Reason, RestData}}
2372 send(Socket, Data, Timeout :: infinity) ->
2374 ok |
2375 {ok, RestData} |
2376 {error, Reason} |
2377 {error, {Reason, RestData}}
2378 send(Socket, Data, Flags, Timeout :: infinity) ->
2380 ok |
2381 {ok, RestData} |
2382 {error, Reason} |
2383 {error, {Reason, RestData}}
2384 Types:
2386 Socket = socket()
2388 Data = iodata()
2389 Flags = [msg_flag() | integer()]
2390 RestData = binary()
2391 Reason = posix() | closed | invalid()
2392 Sends data on a connected socket, waiting for it to be sent.
2394 This call will not return until the Data has been accepted by
2396 the platform's network layer, or it reports an error.
2397 The message Flags may be symbolic msg_flag()s and/or integer()s,
2399 matching the platform's appropriate header files. The values of
2400 all symbolic flags and integers are or:ed together.
2401 The Data, if it is not a binary(), is copied into one before
2403 calling the platform network API, because a single buffer is re‐
2404 quired. A returned RestData is a sub binary of this data binary.
2405 The return value indicates the result from the platform's net‐
2407 work layer:
2408 ok:
2410 All data has been accepted.
2411 {ok, RestData}:
2413 Not all data has been accepted, but no error has been re‐
2414 ported. RestData is the tail of Data that has not been ac‐
2415 cepted.
2416 This cannot happen for a socket of type stream where a par‐
2418 tially successful send is retried until the data is either
2419 accepted or there is an error.
2420 For a socket of type dgram this should probably also not
2422 happen since a message that cannot be passed atomically
2423 should render an error.
2424 It is nevertheless possible for the platform's network layer
2426 to return this.
2427 {error, Reason}:
2429 An error has been reported and no data has been accepted.
2430 The posix() Reasons are from the platform's network layer.
2431 closed means that this socket library knows that the socket
2432 is closed, and invalid() means that something about an argu‐
2433 ment is invalid.
2434 {error, {Reason, RestData}} :
2436 An error has been reported but before that some data was ac‐
2437 cepted. RestData is the tail of Data that has not been ac‐
2438 cepted. See {error, Reason} above.
2439 This can only happen for a socket of type stream when a par‐
2441 tially successful send is retried until there is an error.
2442 send(Socket, Data, Timeout :: integer() >= 0) ->
2444 ok |
2445 {ok, RestData} |
2446 {error, Reason | timeout} |
2447 {error, {Reason | timeout, RestData}}
2448 send(Socket, Data, Flags, Timeout :: integer() >= 0) ->
2450 ok |
2451 {ok, RestData} |
2452 {error, Reason | timeout} |
2453 {error, {Reason | timeout, RestData}}
2454 Types:
2456 Socket = socket()
2458 Data = iodata()
2459 Flags = [msg_flag() | integer()]
2460 RestData = binary()
2461 Reason = posix() | closed | invalid()
2462 Sends data on a connected socket, waiting at most Timeout mil‐
2464 liseconds for it to be sent.
2465 The same as infinite time-out send/2,3,4 but returns {error,
2467 timeout} or {error, {timeout, RestData}} after Timeout millisec‐
2468 onds, if no Data or only some of it was accepted by the plat‐
2469 form's network layer.
2470 send(Socket, Data, SelectHandle :: nowait) ->
2472 ok |
2473 {ok, RestData} |
2474 {select, SelectInfo} |
2475 {select, {SelectInfo, RestData}} |
2476 {error, Reason}
2477 send(Socket, Data, SelectHandle :: select_handle()) ->
2479 ok |
2480 {ok, RestData} |
2481 {select, SelectInfo} |
2482 {select, {SelectInfo, RestData}} |
2483 {error, Reason}
2484 send(Socket, Data, Flags, SelectHandle :: nowait) ->
2486 ok |
2487 {ok, RestData} |
2488 {select, SelectInfo} |
2489 {select, {SelectInfo, RestData}} |
2490 {error, Reason}
2491 send(Socket, Data, Flags, SelectHandle :: select_handle()) ->
2493 ok |
2494 {ok, RestData} |
2495 {select, SelectInfo} |
2496 {select, {SelectInfo, RestData}} |
2497 {error, Reason}
2498 Types:
2500 Socket = socket()
2502 Data = iodata()
2503 Flags = [msg_flag() | integer()]
2504 RestData = binary()
2505 SelectInfo = select_info()
2506 Reason = posix() | closed | invalid()
2507 Sends data on a connected socket, but returns a select continua‐
2509 tion if the data could not be sent immediately.
2510 The same as infinite time-out send/2,3 but if the data is not
2512 immediately accepted by the platform network layer, the function
2513 returns {select, SelectInfo}, and the caller will then receive a
2514 select message, {'$socket', Socket, select, SelectHandle} ( with
2515 the SelectHandle that was contained in the SelectInfo ) when
2516 there is room for more data. A subsequent call to send/2-4 will
2517 then send the data.
2518 If SelectHandle is a select_handle(), that term will be con‐
2520 tained in a returned SelectInfo and the corresponding select
2521 message. The SelectHandle is presumed to be unique to this call.
2522 If SelectHandle is nowait, and a SelectInfo is returned, it will
2524 contain a select_handle() generated by the call.
2525 If some of the data was sent, the function will return {ok,
2527 {RestData, SelectInfo}, which can only happen for a socket of
2528 type stream. If the caller does not want to wait to send the
2529 rest of the data, it should immediately cancel the operation
2530 with cancel/2.
2531 send(Socket, Data, Cont) ->
2533 ok |
2534 {ok, RestData} |
2535 {error, Reason} |
2536 {error, {Reason, RestData}}
2537 send(Socket, Data, Cont, Timeout :: infinity) ->
2539 ok |
2540 {ok, RestData} |
2541 {error, Reason} |
2542 {error, {Reason, RestData}}
2543 send(Socket, Data, Cont, Timeout :: integer() >= 0) ->
2545 ok |
2546 {ok, RestData} |
2547 {error, Reason | timeout} |
2548 {error, {Reason | timeout, RestData}}
2549 send(Socket, Data, Cont, SelectHandle :: nowait) ->
2551 ok |
2552 {ok, RestData} |
2553 {select, SelectInfo} |
2554 {select, {SelectInfo, RestData}} |
2555 {error, Reason}
2556 send(Socket, Data, Cont, SelectHandle :: select_handle()) ->
2558 ok |
2559 {ok, RestData} |
2560 {select, SelectInfo} |
2561 {select, {SelectInfo, RestData}} |
2562 {error, Reason}
2563 Types:
2565 Socket = socket()
2567 Data = iodata()
2568 Cont = select_info()
2569 RestData = binary()
2570 SelectInfo = select_info()
2571 Reason = posix() | closed | invalid()
2572 Continues sending data on a connected socket, where the send op‐
2574 eration was initiated by send/3,4 that returned a SelectInfo
2575 continuation. Otherwise like infinite time-out send/2,3,4 ,
2576 limited time-out send/3,4 or nowait send/3,4 respectively.
2577 Cont is the SelectInfo that was returned from the previous
2579 send() call.
2580 If Data is not a binary(), it will be copied into one, again.
2582 The return value indicates the result from the platform's net‐
2584 work layer. See send/2,3,4 and nowait send/3,4.
2585 sendmsg(Socket, Msg) ->
2587 ok |
2588 {ok, RestData} |
2589 {error, Reason} |
2590 {error, {Reason, RestData}}
2591 sendmsg(Socket, Msg, Flags) ->
2593 ok |
2594 {ok, RestData} |
2595 {error, Reason} |
2596 {error, {Reason, RestData}}
2597 sendmsg(Socket, Msg, Timeout :: infinity) ->
2599 ok |
2600 {ok, RestData} |
2601 {error, Reason} |
2602 {error, {Reason, RestData}}
2603 sendmsg(Socket, Msg, Flags, Timeout :: infinity) ->
2605 ok |
2606 {ok, RestData} |
2607 {error, Reason} |
2608 {error, {Reason, RestData}}
2609 Types:
2611 Socket = socket()
2613 Msg = msg_send()
2614 Flags = [msg_flag() | integer()]
2615 RestData = erlang:iovec()
2616 Reason = posix() | closed | invalid()
2617 Sends a message on a socket, waiting for it to be sent.
2619 The destination, if needed, that is: if the socket is not con‐
2621 nected, is provided in Msg, which also contains the data to send
2622 as a list of binaries. Msg may also contain an list of optional
2623 control messages (depending on what the protocol and platform
2624 supports).
2625 For a connected socket no address field should be present in
2627 Msg, the platform may return an error or ignore one.
2628 The message data is given to to the platform's network layer in
2630 the form of an I/O vector without copying the content. If the
2631 number of elements in the I/O vector is larger than allowed on
2632 the platform (reported in the iov_max field from info/0), on a
2633 socket of type stream the send is iterated over all elements,
2634 but for other socket types the call fails.
2635 This call will not return until the data has been handed over to
2637 the platform's network layer, or when it reports an error.
2638 The message Flags may be symbolic msg_flag()s and/or integer()s,
2640 matching the platform's appropriate header files. The values of
2641 all symbolic flags and integers are or:ed together.
2642 The return value indicates the result from the platform's net‐
2644 work layer. See send/2,3,4.
2645 sendmsg(Socket, Msg, Timeout :: integer() >= 0) ->
2647 ok |
2648 {ok, RestData} |
2649 {error, Reason | timeout} |
2650 {error, {Reason | timeout, RestData}}
2651 sendmsg(Socket, Msg, Flags, Timeout :: integer() >= 0) ->
2653 ok |
2654 {ok, RestData} |
2655 {error, Reason | timeout} |
2656 {error, {Reason | timeout, RestData}}
2657 Types:
2659 Socket = socket()
2661 Msg = msg_send()
2662 Flags = [msg_flag() | integer()]
2663 RestData = erlang:iovec()
2664 Reason = posix() | closed | invalid()
2665 Sends a message on a socket, waiting at most Timeout millisec‐
2667 onds for it to be sent.
2668 The same as infinite time-out sendmsg/2,3,4 but returns {error,
2670 timeout} or {error, {timeout, RestData}} after Timeout millisec‐
2671 onds, if no data or only some of it was accepted by the plat‐
2672 form's network layer.
2673 sendmsg(Socket, Msg, Timeout :: nowait) ->
2675 ok |
2676 {ok, RestData} |
2677 {select, SelectInfo} |
2678 {select, {SelectInfo, RestData}} |
2679 {error, Reason} |
2680 {error, {Reason, RestData}}
2681 sendmsg(Socket, Msg, SelectHandle :: select_handle()) ->
2683 ok |
2684 {ok, RestData} |
2685 {select, SelectInfo} |
2686 {select, {SelectInfo, RestData}} |
2687 {error, Reason} |
2688 {error, {Reason, RestData}}
2689 sendmsg(Socket, Msg, Flags, SelectHandle :: nowait) ->
2691 ok |
2692 {ok, RestData} |
2693 {select, SelectInfo} |
2694 {select, {SelectInfo, RestData}} |
2695 {error, Reason} |
2696 {error, {Reason, RestData}}
2697 sendmsg(Socket, Msg, Flags, SelectHandle :: select_handle()) ->
2699 ok |
2700 {ok, RestData} |
2701 {select, SelectInfo} |
2702 {select, {SelectInfo, RestData}} |
2703 {error, Reason} |
2704 {error, {Reason, RestData}}
2705 Types:
2707 Socket = socket()
2709 Msg = msg_send()
2710 Flags = [msg_flag() | integer()]
2711 RestData = erlang:iovec()
2712 SelectInfo = select_info()
2713 Reason = posix() | closed | invalid()
2714 Sends a message on a socket, but returns a select continuation
2716 if the data could not be sent immediately.
2717 The same as infinity time-out sendmsg/2,3 but if the data is
2719 not immediately accepted by the platform network layer, the
2720 function returns {select, SelectInfo}, and the caller will then
2721 receive a select message, {'$socket', Socket, select, Selec‐
2722 tHandle} ( with the SelectHandle that was contained in the Se‐
2723 lectInfo ) when there is room for more data. A subsequent call
2724 to sendmsg/2-4 will then send the data.
2725 If SelectHandle, is a select_handle(), that term will be con‐
2727 tained in a returned SelectInfo and the corresponding select
2728 message. The SelectHandle is presumed to be unique to this call.
2729 If SelectHandle is nowait, and a SelectInfo is returned, it will
2731 contain a select_handle() generated by the call.
2732 If some of the data was sent, the function will return {ok,
2734 {RestData, SelectInfo}, which can only happen for a socket of
2735 type stream. If the caller does not want to wait to send the
2736 rest of the data, it should immediately cancel the operation
2737 with cancel/2.
2738 sendmsg(Socket, Data, Cont) ->
2740 ok |
2741 {ok, RestData} |
2742 {error, Reason} |
2743 {error, {Reason, RestData}}
2744 sendmsg(Socket, Data, Cont, Timeout :: infinity) ->
2746 ok |
2747 {ok, RestData} |
2748 {error, Reason} |
2749 {error, {Reason, RestData}}
2750 sendmsg(Socket, Data, Cont, Timeout :: integer() >= 0) ->
2752 ok |
2753 {ok, RestData} |
2754 {error, Reason | timeout} |
2755 {error, {Reason | timeout, RestData}}
2756 sendmsg(Socket, Data, Cont, SelectHandle :: nowait) ->
2758 ok |
2759 {ok, RestData} |
2760 {select, SelectInfo} |
2761 {select, {SelectInfo, RestData}} |
2762 {error, Reason} |
2763 {error, {Reason, RestData}}
2764 sendmsg(Socket, Data, Cont, SelectHandle :: select_handle()) ->
2766 ok |
2767 {ok, RestData} |
2768 {select, SelectInfo} |
2769 {select, {SelectInfo, RestData}} |
2770 {error, Reason} |
2771 {error, {Reason, RestData}}
2772 Types:
2774 Socket = socket()
2776 Data = msg_send() | erlang:iovec()
2777 Cont = select_info()
2778 RestData = erlang:iovec()
2779 SelectInfo = select_info()
2780 Reason = posix() | closed | invalid()
2781 Continues sending a message data on a socket, where the send op‐
2783 eration was initiated by sendmsg/3,4 that returned a SelectInfo
2784 continuation. Otherwise like infinite time-out sendmsg/2,3,4 ,
2785 limited time-out sendmsg/3,4 or nowait sendmsg/3,4 respec‐
2786 tively.
2787 Cont is the SelectInfo that was returned from the previous
2789 sendmsg() call.
2790 The return value indicates the result from the platform's net‐
2792 work layer. See send/2,3,4 and nowait sendmsg/3,4.
2793 sendto(Socket, Data, Dest) ->
2795 ok |
2796 {ok, RestData} |
2797 {error, Reason} |
2798 {error, {Reason, RestData}}
2799 sendto(Socket, Data, Dest, Flags) ->
2801 ok |
2802 {ok, RestData} |
2803 {error, Reason} |
2804 {error, {Reason, RestData}}
2805 sendto(Socket, Data, Dest, Timeout :: infinity) ->
2807 ok |
2808 {ok, RestData} |
2809 {error, Reason} |
2810 {error, {Reason, RestData}}
2811 sendto(Socket, Data, Dest, Flags, Timeout :: infinity) ->
2813 ok |
2814 {ok, RestData} |
2815 {error, Reason} |
2816 {error, {Reason, RestData}}
2817 Types:
2819 Socket = socket()
2821 Data = iodata()
2822 Dest = sockaddr()
2823 Flags = [msg_flag() | integer()]
2824 RestData = binary()
2825 Reason = posix() | closed | invalid()
2826 Sends data on a socket, to the specified destination, waiting
2828 for it to be sent.
2829 This call will not return until the data has been accepted by
2831 the platform's network layer, or it reports an error.
2832 If this call is used on a connection mode socket or on a con‐
2834 nected socket, the platforms's network layer may return an error
2835 or ignore the destination address.
2836 The message Flags may be symbolic msg_flag()s and/or integer()s,
2838 matching the platform's appropriate header files. The values of
2839 all symbolic flags and integers are or:ed together.
2840 The return value indicates the result from the platform's net‐
2842 work layer. See send/2,3,4.
2843 sendto(Socket, Data, Dest, Timeout :: integer() >= 0) ->
2845 ok |
2846 {ok, RestData} |
2847 {error, Reason | timeout} |
2848 {error, {Reason | timeout, RestData}}
2849 sendto(Socket, Data, Dest, Flags, Timeout :: integer() >= 0) ->
2851 ok |
2852 {ok, RestData} |
2853 {error, Reason | timeout} |
2854 {error, {Reason | timeout, RestData}}
2855 Types:
2857 Socket = socket()
2859 Data = iodata()
2860 Dest = sockaddr()
2861 Flags = [msg_flag() | integer()]
2862 RestData = binary()
2863 Reason = posix() | closed | invalid()
2864 Sends data on a socket, waiting at most Timeout milliseconds for
2866 it to be sent.
2867 The same as infinite time-out sendto/3,4,5 but returns {error,
2869 timeout} or {error, {timeout, RestData}} after Timeout millisec‐
2870 onds, if no Data or only some of it was accepted by the plat‐
2871 form's network layer.
2872 sendto(Socket, Data, Dest, SelectHandle :: nowait) ->
2874 ok |
2875 {ok, RestData} |
2876 {select, SelectInfo} |
2877 {select, {SelectInfo, RestData}} |
2878 {error, Reason}
2879 sendto(Socket, Data, Dest, SelectHandle :: select_handle()) ->
2881 ok |
2882 {ok, RestData} |
2883 {select, SelectInfo} |
2884 {select, {SelectInfo, RestData}} |
2885 {error, Reason}
2886 sendto(Socket, Data, Dest, Flags, SelectHandle :: nowait) ->
2888 ok |
2889 {ok, RestData} |
2890 {select, SelectInfo} |
2891 {select, {SelectInfo, RestData}} |
2892 {error, Reason}
2893 sendto(Socket, Data, Dest, Flags, SelectHandle :: select_handle()) ->
2895 ok |
2896 {ok, RestData} |
2897 {select, SelectInfo} |
2898 {select, {SelectInfo, RestData}} |
2899 {error, Reason}
2900 Types:
2902 Socket = socket()
2904 Data = iodata()
2905 Dest = sockaddr()
2906 Flags = [msg_flag() | integer()]
2907 RestData = binary()
2908 SelectInfo = select_info()
2909 Reason = posix() | closed | invalid()
2910 Sends data on a socket, but returns a select continuation if the
2912 data could not be sent immediately.
2913 The same as infinity time-out sendto/3,4 but if the data is not
2915 immediately accepted by the platform network layer, the function
2916 returns {select, SelectInfo}, and the caller will then receive a
2917 select message, {'$socket', Socket, select, SelectHandle} ( with
2918 the SelectHandle that was contained in the SelectInfo ) when
2919 there is room for more data. A subsequent call to sendto/3-5
2920 will then send the data.
2921 If SelectHandle is a select_handle(), that term will be con‐
2923 tained in a returned SelectInfo and the corresponding select
2924 message. The SelectHandle is presumed to be unique to this call.
2925 If SelectHandle is nowait, and a SelectInfo is returned, it will
2927 contain a select_handle() generated by the call.
2928 If some of the data was sent, the function will return {ok,
2930 {RestData, SelectInfo}, which can only happen for a socket of
2931 type stream. If the caller does not want to wait to send the
2932 rest of the data, it should immediately cancel the operation
2933 with cancel/2.
2934 sendto(Socket, Data, Cont) ->
2936 ok |
2937 {ok, RestData} |
2938 {error, Reason} |
2939 {error, {Reason, RestData}}
2940 sendto(Socket, Data, Cont, Timeout :: infinity) ->
2942 ok |
2943 {ok, RestData} |
2944 {error, Reason} |
2945 {error, {Reason, RestData}}
2946 sendto(Socket, Data, Cont, Timeout :: integer() >= 0) ->
2948 ok |
2949 {ok, RestData} |
2950 {error, Reason | timeout} |
2951 {error, {Reason | timeout, RestData}}
2952 sendto(Socket, Data, Cont, SelectHandle :: nowait) ->
2954 ok |
2955 {ok, RestData} |
2956 {select, SelectInfo} |
2957 {select, {SelectInfo, RestData}} |
2958 {error, Reason}
2959 sendto(Socket, Data, Cont, SelectHandle :: select_handle()) ->
2961 ok |
2962 {ok, RestData} |
2963 {select, SelectInfo} |
2964 {select, {SelectInfo, RestData}} |
2965 {error, Reason}
2966 Types:
2968 Socket = socket()
2970 Data = iodata()
2971 Cont = select_info()
2972 RestData = binary()
2973 SelectInfo = select_info()
2974 Reason = posix() | closed | invalid()
2975 Continues sending data on a socket, where the send operation was
2977 initiated by sendto/4,5 that returned a SelectInfo continuation.
2978 Otherwise like infinite time-out sendto/3,4,5 , limited time-
2979 out sendto/4,5 or nowait sendto/4,5 respectively.
2980 Cont is the SelectInfo that was returned from the previous
2982 sendto() call.
2983 If Data is not a binary(), it will be copied into one, again.
2985 The return value indicates the result from the platform's net‐
2987 work layer. See send/2,3,4 and nowait sendto/4,5.
2988 sendfile(Socket, FileHandle, Offset, Count, Timeout :: infinity) ->
2990 {ok, BytesSent} |
2991 {error, Reason} |
2992 {error, {Reason, BytesSent}}
2993 Types:
2995 Socket = socket()
2997 FileHandle = file:fd()
2998 Offset = integer()
2999 Count = BytesSent = integer() >= 0
3000 Reason = posix() | closed | invalid()
3001 Sends file data on a socket, to the specified destination, wait‐
3003 ing for it to be sent ("infinite" time-out).
3004 The FileHandle must refer to an open raw file as described in
3006 file:open/2.
3007 This call will not return until the data has been accepted by
3009 the platform's network layer, or it reports an error.
3010 The Offset argument is the file offset to start reading from.
3012 The default value is 0.
3013 The Count argument is the number of bytes to transfer from File‐
3015 Handle to Socket. If Count =:= 0 (the default) the transfer
3016 stops at the end of file.
3017 The return value indicates the result from the platform's net‐
3019 work layer:
3020 {ok, BytesSent}:
3022 The transfer completed successfully after BytesSent bytes of
3023 data.
3024 {error, Reason}:
3026 An error has been reported and no data has been transferred.
3027 The posix() Reasons are from the platform's network layer.
3028 closed means that this socket library knows that the socket
3029 is closed, and invalid() means that something about an argu‐
3030 ment is invalid.
3031 {error, {Reason, BytesSent}} :
3033 An error has been reported but before that some data was
3034 transferred. See {error, Reason} and {ok, BytesSent} above.
3035 sendfile(Socket, FileHandle, Offset, Count,
3037 Timeout :: integer() >= 0) ->
3038 {ok, BytesSent} |
3039 {error, Reason | timeout} |
3040 {error, {Reason | timeout, BytesSent}}
3041 Types:
3043 Socket = socket()
3045 FileHandle = file:fd()
3046 Offset = integer()
3047 Count = BytesSent = integer() >= 0
3048 Reason = posix() | closed | invalid()
3049 Sends file data on a socket, waiting at most Timeout millisec‐
3051 onds for it to be sent (limited time-out).
3052 The same as "infinite" time-out sendfile/5 but returns {error,
3054 timeout} or {error, {timeout, BytesSent}} after Timeout mil‐
3055 liseconds, if not all file data was transferred by the plat‐
3056 form's network layer.
3057 sendfile(Socket, FileHandle, Offset, Count,
3059 SelectHandle :: nowait) ->
3060 {ok, BytesSent} |
3061 {select, SelectInfo} |
3062 {select, {SelectInfo, BytesSent}} |
3063 {error, Reason}
3064 sendfile(Socket, FileHandle, Offset, Count,
3066 SelectHandle :: select_handle()) ->
3067 {ok, BytesSent} |
3068 {select, SelectInfo} |
3069 {select, {SelectInfo, BytesSent}} |
3070 {error, Reason}
3071 Types:
3073 Socket = socket()
3075 FileHandle = file:fd()
3076 Offset = integer()
3077 Count = BytesSent = integer() >= 0
3078 SelectInfo = select_info()
3079 Reason = posix() | closed | invalid()
3080 Sends file data on a socket, but returns a select continuation
3082 if the data could not be sent immediately (nowait).
3083 The same as "infinite" time-out sendfile/5 but if the data is
3085 not immediately accepted by the platform network layer, the
3086 function returns {select, SelectInfo}, and the caller will then
3087 receive a select message, {'$socket', Socket, select, Selec‐
3088 tHandle} ( with the SelectHandle that was contained in the Se‐
3089 lectInfo ) when there is room for more data. Then a call to
3090 sendfile/3 with SelectInfo as the second argument will continue
3091 the data transfer.
3092 If SelectHandle is a select_handle(), that term will be con‐
3094 tained in a returned SelectInfo and the corresponding select
3095 message. The SelectHandle is presumed to be unique to this call.
3096 If SelectHandle is nowait, and a SelectInfo is returned, it will
3098 contain a select_handle() generated by the call.
3099 If some file data was sent, the function will return {ok,
3101 {BytesSent, SelectInfo}. If the caller does not want to wait to
3102 send the rest of the data, it should immediately cancel the op‐
3103 eration with cancel/2.
3104 sendfile(Socket, Cont, Offset, Count, Timeout :: infinity) ->
3106 {ok, BytesSent} |
3107 {error, Reason} |
3108 {error, {Reason, BytesSent}}
3109 sendfile(Socket, Cont, Offset, Count,
3111 Timeout :: integer() >= 0) ->
3112 {ok, BytesSent} |
3113 {error, Reason | timeout} |
3114 {error, {Reason | timeout, BytesSent}}
3115 sendfile(Socket, Cont, Offset, Count, SelectHandle :: nowait) ->
3117 {ok, BytesSent} |
3118 {select, SelectInfo} |
3119 {select, {SelectInfo, BytesSent}} |
3120 {error, Reason}
3121 sendfile(Socket, Cont, Offset, Count,
3123 SelectHandle :: select_handle()) ->
3124 {ok, BytesSent} |
3125 {select, SelectInfo} |
3126 {select, {SelectInfo, BytesSent}} |
3127 {error, Reason}
3128 Types:
3130 Socket = socket()
3132 Cont = select_info()
3133 Offset = integer()
3134 Count = BytesSent = integer() >= 0
3135 SelectInfo = select_info()
3136 Reason = posix() | closed | invalid()
3137 Continues sending file data on a socket, where the send opera‐
3139 tion was initiated by sendfile/3,5 that returned a SelectInfo
3140 continuation. Otherwise like "infinite" time-out sendfile/5 ,
3141 limited time-out sendfile/5 or nowait sendfile/5 respectively.
3142 Cont is the SelectInfo that was returned from the previous send‐
3144 file() call.
3145 The return value indicates the result from the platform's net‐
3147 work layer. See "infinite" time-out sendfile/5.
3148 sendfile(Socket, FileHandle, Offset, Count) -> Result
3150 Types:
3152 Socket = socket()
3154 FileHandle = file:fd()
3155 Offset = integer()
3156 Count = integer() >= 0
3157 The same as sendfile(Socket, FileHandle, Offset, Count, infin‐
3159 ity), that is: send the file data at Offset and Count to the
3160 socket, without time-out other than from the platform's network
3161 stack.
3162 sendfile(Socket, FileHandle, Timeout) -> Result
3164 Types:
3166 Socket = socket()
3168 FileHandle = file:fd()
3169 Timeout = timeout() | 'nowait' | select_handle()
3170 Depending on the Timeout argument; the same as sendfile(Socket,
3172 FileHandle, 0, 0, infinity), sendfile(Socket, FileHandle, 0,
3173 0, Timeout), or sendfile(Socket, FileHandle, 0, 0, Selec‐
3174 tHandle), that is: send all data in the file to the socket,
3175 with the given Timeout.
3176 sendfile(Socket, FileHandle) -> Result
3178 Types:
3180 Socket = socket()
3182 FileHandle = file:fd()
3183 The same as sendfile(Socket, FileHandle, 0, 0, infinity), that
3185 is: send all data in the file to the socket, without time-out
3186 other than from the platform's network stack.
3187 setopt(Socket :: socket(),
3189 SocketOption :: {Level :: otp, Opt :: otp_socket_option()},
3190 Value :: term()) ->
3191 ok | {error, invalid() | closed}
3192 Sets a socket option in the protocol level otp, which is this
3194 implementation's level above the OS protocol layers.
3195 See the type otp_socket_option() for a description of the op‐
3197 tions on this level.
3198 setopt(Socket :: socket(),
3200 SocketOption :: socket_option(),
3201 Value :: term()) ->
3202 ok | {error, posix() | invalid() | closed}
3203 Set a socket option in one of the OS's protocol levels. See the
3205 type socket_option() for which options that this implementation
3206 knows about, how they are related to option names in the OS, and
3207 if there are known peculiarities with any of them.
3208 What options are valid depends on what kind of socket it is (do‐
3210 main(), type() and protocol()).
3211 See the socket options chapter of the users guide for more
3213 info.
3214 Note:
3216 Not all options are valid, nor possible to set, on all plat‐
3217 forms. That is, even if "we" support an option; it does not mean
3218 that the underlying OS does.
3219 setopt(Socket, Level, Opt, Value) -> ok | {error, Reason}
3222 Types:
3224 Socket = socket()
3226 Value = term()
3227 Reason = inet:posix() | invalid() | closed
3228 Backwards compatibility function.
3230 The same as setopt(Socket, {Level, Opt}, Value)
3232 setopt_native(Socket :: socket(),
3234 SocketOption ::
3235 socket_option() |
3236 {Level :: level() | (NativeLevel :: integer()),
3237 NativeOpt :: integer()},
3238 Value :: native_value()) ->
3239 ok | {error, posix() | invalid() | closed}
3240 Sets a socket option that may be unknown to our implementation,
3242 or that has a type not compatible with our implementation, that
3243 is; in "native mode".
3244 If Value is an integer() it will be used as a C type (int), if
3246 it is a boolean() it will be used as a C type (int) with the C
3247 implementations values for false or true, and if it is a bi‐
3248 nary() its content and size will be used as the option value.
3249 The socket option may be specified with an ordinary socket_op‐
3251 tion() tuple, with a known Level = level() and an integer Na‐
3252 tiveOpt, or with both an integer NativeLevel and NativeOpt.
3253 What options are valid depends on what kind of socket it is (do‐
3255 main(), type() and protocol()).
3256 The integer values for NativeLevel and NativeOpt as well as the
3258 encoding of Value has to be deduced from the header files for
3259 the running system.
3260 shutdown(Socket, How) -> ok | {error, Reason}
3262 Types:
3264 Socket = socket()
3266 How = read | write | read_write
3267 Reason = posix() | closed
3268 Shut down all or part of a full-duplex connection.
3270 sockname(Socket) -> {ok, SockAddr} | {error, Reason}
3272 Types:
3274 Socket = socket()
3276 SockAddr = sockaddr_recv()
3277 Reason = posix() | closed
3278 Returns the current address to which the socket is bound.
3280 supports() ->
3282 [{Key1 :: term(),
3283 boolean() |
3284 [{Key2 :: term(),
3285 boolean() | [{Key3 :: term(), boolean()}]}]}]
3286 supports(Key1 :: term()) ->
3288 [{Key2 :: term(),
3289 boolean() | [{Key3 :: term(), boolean()}]}]
3290 supports(Key1 :: term(), Key2 :: term()) ->
3292 [{Key3 :: term(), boolean()}]
3293 These functions function retrieves information about what the
3295 platform supports, such which platform features or which socket
3296 options, are supported.
3297 For keys other than the known the empty list is returned, Note
3299 that in a future version or on a different platform there might
3300 be more supported items.
3301 supports():
3303 Returns a list of {Key1, supports(Key1)} tuples for every
3304 Key1 described in supports/1 and {Key1, boolean()} tuples
3305 for each of the following keys:
3306 sctp:
3308 SCTP support
3309 ipv6:
3311 IPv6 support
3312 local:
3314 Unix Domain sockets support (AF_UNIX | AF_LOCAL)
3315 netns:
3317 Network Namespaces support (Linux, setns(2))
3318 sendfile:
3320 Sendfile support (sendfile(2))
3321 supports(msg_flags = Key1):
3323 Returns a list of {Flag, boolean()} tuples for every Flag in
3324 msg_flag() with the boolean() indicating if the flag is sup‐
3325 ported on this platform.
3326 supports(protocols = Key1):
3328 Returns a list of {Name :: atom(), boolean()} tuples for ev‐
3329 ery Name in protocol() with the boolean() indicating if the
3330 protocol is supported on this platform.
3331 supports(options = Key1):
3333 Returns a list of {SocketOption, boolean()} tuples for every
3334 SocketOption in socket_option() with the boolean() indicat‐
3335 ing if the socket option is supported on this platform.
3336 supports(options = Key1, Key2) :
3338 For a Key2 in level() returns a list of {Opt, boolean()} tu‐
3339 ples for all known socket options Opt on that Level =:=
3340 Key2, and the boolean() indicating if the socket option is
3341 supported on this platform. See setopt/3 and getopt/2.
3342 use_registry(D :: boolean()) -> ok
3344 Globally change if the socket registry is to be used or not.
3346 Note that its still possible to override this explicitly when
3347 creating an individual sockets, see open/2 or open/4 for more
3348 info (use the Extra argument).
3349 which_sockets() -> [socket()]
3351 which_sockets(FilterRule) -> [socket()]
3353 Types:
3355 FilterRule =
3357 inet | inet6 | local | stream | dgram | seqpacket | sctp
3358 |
3359 tcp | udp |
3360 pid() |
3361 fun((socket_info()) -> boolean())
3362 Returns a list of all sockets, according to the filter rule.
3364 There are several pre-made filter rule(s) and one general:
3366 inet | inet6:
3368 Selection based on the domain of the socket.
3369 Only a subset is valid.
3370 stream | dgram | seqpacket:
3372 Selection based on the type of the socket.
3373 Only a subset is valid.
3374 sctp | tcp | udp:
3376 Selection based on the protocol of the socket.
3377 Only a subset is valid.
3378 pid():
3380 Selection base on which sockets has this pid as Controlling
3381 Process.
3382 fun((socket_info()) -> boolean()):
3384 The general filter rule.
3385 A fun that takes the socket info and returns a boolean()
3386 (true if the socket could be included and false if should
3387 not).
3388
3390 client(SAddr, SPort) ->
3391 {ok, Sock} = socket:open(inet, stream, tcp),
3392 ok = socket:connect(Sock, #{family => inet,
3393 addr => SAddr,
3394 port => SPort}),
3395 Msg = <<"hello">>,
3396 ok = socket:send(Sock, Msg),
3397 ok = socket:shutdown(Sock, write),
3398 {ok, Msg} = socket:recv(Sock),
3399 ok = socket:close(Sock).
3400 server(Addr, Port) ->
3402 {ok, LSock} = socket:open(inet, stream, tcp),
3403 ok = socket:bind(LSock, #{family => inet,
3404 port => Port,
3405 addr => Addr}),
3406 ok = socket:listen(LSock),
3407 {ok, Sock} = socket:accept(LSock),
3408 {ok, Msg} = socket:recv(Sock),
3409 ok = socket:send(Sock, Msg),
3410 ok = socket:close(Sock),
3411 ok = socket:close(LSock).
3412Ericsson AB kernel 8.5.3 socket(3)