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