1socket(3) Erlang Module Definition socket(3)
2
6 socket - Socket interface.
7
9 This module provides an API for network socket. Functions are provided
10 to create, delete and manupilate the sockets aswell as sending and re‐
11 civing data on them.
12 The intent is that it shall be as "close as possible" to the OS level
14 socket interface. The only significant addition is that some of the
15 functions, e.g. recv/3, has a timeout argument.
16 Note:
18 Some functions allow for an asynchronous call. This is achieved by
19 setting the Timeout argument to nowait. For instance, if calling the
20 recv/3 function with Timeout set to nowait (recv(Sock, 0, nowait)) when
21 there is actually nothing to read, it will return with {select, Se‐
22 lectInfo} (SelectInfo contains the SelectRef). When data eventually ar‐
23 rives a 'select' message will be sent to the caller:
24 : {'$socket', socket(), select, SelectRef}
26 The caller can now make another call to the recv function and now ex‐
28 pect data.
29 Note that all other users are locked out until the 'current user' has
31 called the function (recv in this case).
32 Another message the user must be prepared for (when making asynchronous
34 calls) is the abort message:
35 : {'$socket', socket(), abort, Info}
37 This message indicates that the (asynchronous) operation has been
39 aborted. If, for instance, the socket has been closed (by another
40 process), Info will be {SelectRef, closed}.
41 Note:
44 There is currently no support for Windows.
45 Support for IPv6 has been implemented but not tested.
47 SCTP has only been partly implemented (and not tested).
49
52 domain() = local | inet | inet6
53 type() = stream | dgram | raw | rdm | seqpacket
55 protocol() =
57 ip | tcp | udp | sctp | icmp | igmp | {raw, integer()}
58 socket()
60 As returned by open/1,2,3,4 and accept/1,2.
62 select_tag()
64 A tag that describes the (select) operation.
66 select_ref()
68 A reference that uniquely identifies the (select) operation.
70 select_info() = {select_info, select_tag(), select_ref()}
72 socket_counters() =
74 #{read_byte := integer() >= 0,
75 read_fails := integer() >= 0,
76 read_pkg := integer() >= 0,
77 read_pkg_max := integer() >= 0,
78 read_tries := integer() >= 0,
79 read_waits := integer() >= 0,
80 write_byte := integer() >= 0,
81 write_fails := integer() >= 0,
82 write_pkg := integer() >= 0,
83 write_pkg_max := integer() >= 0,
84 write_tries := integer() >= 0,
85 write_waits := integer() >= 0,
86 acc_success := integer() >= 0,
87 acc_fails := integer() >= 0,
88 acc_tries := integer() >= 0,
89 acc_waits := integer() >= 0}
90 socket_info() =
92 #{domain := domain(),
93 type := type(),
94 protocol := protocol(),
95 ctrl := pid(),
96 ctype := normal | fromfd | {fromfd, integer()},
97 counters := socket_counters(),
98 num_readers := integer() >= 0,
99 num_writers := integer() >= 0,
100 num_acceptors := integer() >= 0,
101 writable := boolean(),
102 readable := boolean()}
103 ip4_address() = {0..255, 0..255, 0..255, 0..255}
105 ip6_address() =
107 {0..65535,
108 0..65535,
109 0..65535,
110 0..65535,
111 0..65535,
112 0..65535,
113 0..65535,
114 0..65535}
115 sockaddr() =
117 sockaddr_in4() |
118 sockaddr_in6() |
119 sockaddr_un() |
120 sockaddr_ll()
121 sockaddr_in4() =
123 #{family := inet,
124 port := port_number(),
125 addr := any | broadcast | loopback | ip4_address()}
126 sockaddr_in6() =
128 #{family := inet6,
129 port := port_number(),
130 addr := any | loopback | ip6_address(),
131 flowinfo := in6_flow_info(),
132 scope_id := in6_scope_id()}
133 sockaddr_un() = #{family := local, path := binary() | string()}
135 sockaddr_ll() =
137 #{family := packet,
138 protocol := integer() >= 0,
139 ifindex := integer(),
140 pkttype := packet_type(),
141 hatype := integer() >= 0,
142 addr := binary()}
143 packet_type() =
145 host | broadcast | multicast | otherhost | outgoing |
146 loopback | user | kernel | fastroute |
147 integer() >= 0
148 port_number() = 0..65535
150 in6_flow_info() = uint20()
152 in6_scope_id() = uint32()
154 send_flags() = [send_flag()]
156 send_flag() = confirm | dontroute | eor | more | nosignal | oob
158 recv_flags() = [recv_flag()]
160 recv_flag() = cmsg_cloexec | errqueue | oob | peek | trunc
162 shutdown_how() = read | write | read_write
164 sockopt_level() =
166 otp | socket | ip | ipv6 | tcp | udp | sctp |
167 integer() >= 0
168 otp_socket_option() =
170 debug | use_registry | iow | controlling_process | rcvbuf |
171 rcvctrlbuf | sndctrlbuf | meta | fd
172 socket_option() =
174 acceptconn | acceptfilter | bindtodevice | broadcast |
175 busy_poll | debug | domain | dontroute | error | keepalive |
176 linger | mark | oobinline | passcred | peek_off | peercred |
177 priority | protocol | rcvbuf | rcvbufforce | rcvlowat |
178 rcvtimeo | reuseaddr | reuseport | rxq_ovfl | setfib |
179 sndbuf | sndbufforce | sndlowat | sndtimeo | timestamp | type
180 ip_socket_option() =
182 add_membership | add_source_membership | block_source |
183 dontfrag | drop_membership | drop_source_membership |
184 freebind | hdrincl | minttl | msfilter | mtu | mtu_discover |
185 multicast_all | multicast_if | multicast_loop |
186 multicast_ttl | nodefrag | options | pktinfo | recverr |
187 recvif | recvdstaddr | recvopts | recvorigdstaddr | recvtos |
188 recvttl | retopts | router_alert | sndsrcaddr | tos |
189 transparent | ttl | unblock_source
190 ipv6_socket_option() =
192 addrform | add_membership | authhdr | auth_level | checksum |
193 drop_membership | dstopts | esp_trans_level |
194 esp_network_level | faith | flowinfo | hopopts |
195 ipcomp_level | join_group | leave_group | mtu | mtu_discover |
196 multicast_hops | multicast_if | multicast_loop | portrange |
197 pktoptions | recverr | recvhoplimit | hoplimit | recvpktinfo |
198 pktinfo | recvtclass | router_alert | rthdr | tclass |
199 unicast_hops | use_min_mtu | v6only
200 tcp_socket_option() =
202 congestion | cork | info | keepcnt | keepidle | keepintvl |
203 maxseg | md5sig | nodelay | noopt | nopush | syncnt |
204 user_timeout
205 udp_socket_option() = cork
207 sctp_socket_option() =
209 adaption_layer | associnfo | auth_active_key | auth_asconf |
210 auth_chunk | auth_key | auth_delete_key | autoclose |
211 context | default_send_params | delayed_ack_time |
212 disable_fragments | hmac_ident | events | explicit_eor |
213 fragment_interleave | get_peer_addr_info | initmsg |
214 i_want_mapped_v4_addr | local_auth_chunks | maxseg |
215 maxburst | nodelay | partial_delivery_point |
216 peer_addr_params | peer_auth_chunks | primary_addr |
217 reset_streams | rtoinfo | set_peer_primary_addr | status |
218 use_ext_recvinfo
219 timeval() = #{sec := integer(), usec := integer()}
221 ip_tos() =
223 lowdelay | throughput | reliability | mincost | integer()
224 ip_mreq() =
226 #{multiaddr := ip4_address(),
227 interface := any | ip4_address()}
228 ip_mreq_source() =
230 #{multiaddr := ip4_address(),
231 interface := ip4_address(),
232 sourceaddr := ip4_address()}
233 ip_pmtudisc() = want | dont | do | probe
235 ip_msfilter_mode() = include | exclude
237 ip_msfilter() =
239 #{multiaddr := ip4_address(),
240 interface := ip4_address(),
241 mode := ip_msfilter_mode(),
242 slist := [ip4_address()]}
243 ip_pktinfo() =
245 #{ifindex := integer() >= 0,
246 spec_dst := ip4_address(),
247 addr := ip4_address()}
248 ipv6_mreq() =
250 #{multiaddr := ip6_address(), interface := integer() >= 0}
251 ipv6_pmtudisc() = ip_pmtudisc()
253 ipv6_pktinfo() = #{addr := ip6_address(), ifindex := integer()}
255 sctp_assoc_id() = int32()
257 sctp_sndrcvinfo() =
259 #{stream := uint16(),
260 ssn := uint16(),
261 flags := uint16(),
262 ppid := uint16(),
263 context := uint16(),
264 timetolive := uint16(),
265 tsn := uint16(),
266 cumtsn := uint16(),
267 assoc_id := sctp_assoc_id()}
268 sctp_event_subscribe() =
270 #{data_in := boolean(),
271 association := boolean(),
272 address := boolean(),
273 send_failure := boolean(),
274 peer_error := boolean(),
275 shutdown := boolean(),
276 partial_delivery := boolean(),
277 adaptation_layer := boolean(),
278 authentication := boolean(),
279 sender_dry := boolean()}
280 sctp_assocparams() =
282 #{assoc_id := sctp_assoc_id(),
283 max_rxt := uint16(),
284 num_peer_dests := uint16(),
285 peer_rwnd := uint32(),
286 local_rwnd := uint32(),
287 cookie_life := uint32()}
288 sctp_initmsg() =
290 #{num_outstreams := uint16(),
291 max_instreams := uint16(),
292 max_attempts := uint16(),
293 max_init_timeo := uint16()}
294 sctp_rtoinfo() =
296 #{assoc_id := sctp_assoc_id(),
297 initial := uint32(),
298 max := uint32(),
299 min := uint32()}
300 msghdr_flag() = ctrunc | eor | errqueue | oob | trunc
302 msghdr_flags() = [msghdr_flag()]
304 msghdr() =
306 #{addr := sockaddr(),
307 iov := [binary()],
308 ctrl := [cmsghdr_recv()] | [cmsghdr_send()],
309 flags := msghdr_flags()}
310 cmsghdr_level() = socket | ip | ipv6 | integer()
312 cmsghdr_type() =
314 credentials | hoplevel | origdstaddr | pktinfo | recvtos |
315 rights | timestamp | tos | ttl |
316 integer()
317 cmsghdr_recv() =
319 #{level := socket, type := timestamp, data := timeval()} |
320 #{level := socket, type := rights, data := binary()} |
321 #{level := socket, type := credentials, data := binary()} |
322 #{level := socket, type := integer(), data := binary()} |
323 #{level := ip, type := tos, data := ip_tos()} |
324 #{level := ip, type := recvtos, data := ip_tos()} |
325 #{level := ip, type := ttl, data := integer()} |
326 #{level := ip, type := recvttl, data := integer()} |
327 #{level := ip, type := pktinfo, data := ip_pktinfo()} |
328 #{level := ip, type := origdstaddr, data := sockaddr_in4()} |
329 #{level := ip,
330 type := recverr,
331 data := extended_err() | binary()} |
332 #{level := ip, type := integer(), data := binary()} |
333 #{level := ipv6, type := hoplevel, data := integer()} |
334 #{level := ipv6, type := pktinfo, data := ipv6_pktinfo()} |
335 #{level := ipv6,
336 type := recverr,
337 data := extended_err() | binary()} |
338 #{level := ipv6, type := tclass, data := integer()} |
339 #{level := ipv6, type := integer(), data := binary()} |
340 #{level := integer(), type := integer(), data := binary()}
341 cmsghdr_send() =
343 #{level := socket, type := timestamp, data := binary()} |
344 #{level := socket, type := rights, data := binary()} |
345 #{level := socket, type := credentials, data := binary()} |
346 #{level := socket, type := integer(), data := binary()} |
347 #{level := ip, type := tos, data := ip_tos() | binary()} |
348 #{level := ip, type := ttl, data := integer() | binary()} |
349 #{level := ip, type := integer(), data := binary()} |
350 #{level := ipv6, type := tclass, data := integer()} |
351 #{level := ipv6, type := integer(), data := binary()} |
352 #{level := udp, type := integer(), data := binary()} |
353 #{level := integer(), type := integer(), data := binary()}
354 icmp_dest_unreach() =
356 net_unreach | host_unreach | port_unreach | frag_needed |
357 net_unknown | host_unknown |
358 uint8()
359 icmpv6_dest_unreach() =
361 noroute | adm_prohibited | not_neighbour | addr_unreach |
362 port_unreach | policy_fail | reject_route |
363 uint8()
364 ee_origin() = none | local | icmp | icmp6 | uint8()
366 extended_err() =
368 #{error := term(),
369 origin := icmp,
370 type := dest_unreach,
371 code := icmp_dest_unreach(),
372 info := uint32(),
373 data := uint32(),
374 offender := undefined | sockaddr()} |
375 #{error := term(),
376 origin := icmp,
377 type := time_exceeded | uint8(),
378 code := uint8(),
379 info := uint32(),
380 data := uint32(),
381 offender := undefined | sockaddr()} |
382 #{error := term(),
383 origin := icmp6,
384 type := dest_unreach,
385 code := icmpv6_dest_unreach(),
386 info := uint32(),
387 data := uint32(),
388 offender := undefined | sockaddr()} |
389 #{error := term(),
390 origin := icmp6,
391 type := pkt_toobig | time_exceeded | uint8(),
392 code := uint8(),
393 info := uint32(),
394 data := uint32(),
395 offender := undefined | sockaddr()} |
396 #{error := term(),
397 origin := ee_origin(),
398 type := uint8(),
399 code := uint8(),
400 info := uint32(),
401 data := uint32(),
402 offender := undefined | sockaddr()}
403 uint8() = 0..255
405 uint16() = 0..65535
407 uint20() = 0..1048575
409 uint32() = 0..4294967295
411 int32() = -2147483648..2147483647
413 errcode() =
415 inet:posix() | exalloc | exmonitor | exselect | exself
416 The POSIX error codes are mostly come from the OS level socket
418 interface, but this module may generate some appropriate POSIX
419 codes.
420 The other values come from this module's lower levels and are
422 all fairly fatal internal errors:
423 exalloc:
425 Memory allocation failed
426 exmonitor:
428 Failed to set a monitor on a process
429 exselect:
431 Select operation failed
432 exself:
434 Failed to get current process
435
437 accept(LSocket) -> {ok, Socket} | {error, Reason}
438 accept(LSocket, Timeout) -> {ok, Socket} | {error, Reason}
440 Types:
442 LSocket = socket()
444 Timeout = timeout()
445 Socket = socket()
446 Reason = errcode() | closed | timeout
447 Accept a connection on a socket.
449 This call is used with connection-based socket types (stream or
451 seqpacket). It extracs the first pending connection request for
452 the listen socket and returns the (newly) connected socket.
453 accept(LSocket, Timeout :: nowait) ->
455 {ok, Socket} | {select, SelectInfo} | {error, Reason}
456 Types:
458 LSocket = Socket = socket()
460 SelectInfo = select_info()
461 Reason = errcode() | closed
462 Accept a connection on a socket.
464 This call is used with connection-based socket types (stream or
466 seqpacket). It extracs the first pending connection request for
467 the listen socket and returns the (newly) connected socket.
468 In the case when there is no connections waiting, the function
470 will return with the SelectInfo. The caller can then await a se‐
471 lect message, {'$socket', Socket, select, Info} (where Info is
472 the ref field from the SelectInfo), when a client connects (a
473 subsequent call to accept will then return the socket).
474 bind(Socket, Addr) -> {ok, Port} | {error, Reason}
476 Types:
478 Socket = socket()
480 Addr = sockaddr() | any | broadcast | loopback
481 Port = port_number()
482 Reason = inet:posix() | closed
483 Bind a name to a socket.
485 When a socket is created (with open), it has no address assigned
487 to it. bind assigns the address specified by the Addr argument.
488 The rules used for name binding vary between domains.
490 cancel(Socket, SelectInfo) -> ok | {error, Reason}
492 Types:
494 Socket = socket()
496 SelectInfo = select_info()
497 Reason = einval | closed | exself
498 Cancel an asynchronous request.
500 Call this function in order to cancel a previous asynchronous
502 call to, e.g. recv/3.
503 close(Socket) -> ok | {error, Reason}
505 Types:
507 Socket = socket()
509 Reason = errcode() | closed | timeout
510 Closes the socket.
512 Note:
514 Note that for e.g. protocol = tcp, most implementations doing a
515 close does not guarantee that any data sent is delivered to the
516 recipient before the close is detected at the remote side.
517 One way to handle this is to use the shutdown function
519 (socket:shutdown(Socket, write)) to signal that no more data is
520 to be sent and then wait for the read side of the socket to be
521 closed.
522 connect(Socket, SockAddr) -> ok | {error, Reason}
525 connect(Socket, SockAddr, Timeout) -> ok | {error, Reason}
527 Types:
529 Socket = socket()
531 SockAddr = sockaddr()
532 Timeout = timeout()
533 Reason = errcode() | closed | timeout
534 This function connects the socket to the address specied by the
536 SockAddr argument.
537 connect(Socket, SockAddr, Timeout :: nowait) ->
539 ok | {select, SelectInfo} | {error, Reason}
540 Types:
542 Socket = socket()
544 SockAddr = sockaddr()
545 SelectInfo = select_info()
546 Reason = errcode() | closed
547 This function connects the socket to the address specied by the
549 SockAddr argument.
550 In the case when its not possible to immediately establish a
552 connection, the function will return with the SelectInfo. The
553 caller can then await a select message, {'$socket', Socket, se‐
554 lect, Info} (where Info is the ref field from the SelectInfo, a
555 subsequent call to connect will then establish the connection).
556 getopt(Socket, Level :: otp, Key :: otp_socket_option()) ->
558 {ok, Value} | {error, Reason}
559 getopt(Socket, Level :: socket, Key :: socket_option()) ->
561 {ok, Value} | {error, Reason}
562 getopt(Socket, Level :: ip, Key :: ip_socket_option()) ->
564 {ok, Value} | {error, Reason}
565 getopt(Socket, Level :: ipv6, Key :: ipv6_socket_option()) ->
567 {ok, Value} | {error, Reason}
568 getopt(Socket, Level :: tcp, Key :: tcp_socket_option()) ->
570 {ok, Value} | {error, Reason}
571 getopt(Socket, Level :: udp, Key :: udp_socket_option()) ->
573 {ok, Value} | {error, Reason}
574 getopt(Socket, Level :: sctp, Key :: sctp_socket_option()) ->
576 {ok, Value} | {error, Reason}
577 Types:
579 Socket = socket()
581 Value = term()
582 Reason = inet:posix() | closed
583 Get an option on a socket.
585 What properties are valid depend both on Level and on what kind
587 of socket it is (domain, type and protocol).
588 See the socket options chapter of the users guide for more info.
590 Note:
592 Not all options are valid on all platforms. That is, even if
593 "we" support an option, that does not mean that the underlying
594 OS does.
595 getopt(Socket, Level, Key) -> ok | {ok, Value} | {error, Reason}
598 Types:
600 Socket = socket()
602 Level = integer()
603 Key = {NativeOpt, ValueSize}
604 NativeOpt = integer()
605 ValueSize = int | bool | integer() >= 0
606 Value = term()
607 Reason = inet:posix() | closed
608 Get an option on a socket.
610 When specifying Level as an integer, and therefor using "native
612 mode", it is *currently* up to the caller to know how to inter‐
613 pret the result.
614 For more info, see getopt above.
616 info(Socket) -> socket_info()
618 Types:
620 Socket = socket()
622 Get miscellaneous info about the socket.
624 The function returns a map with each info item as a key-value
626 binding. It reflects the "current" state of the socket.
627 Note:
629 In order to ensure data integrity, mutex'es are taken when
630 needed. So, do not call this function often.
631 listen(Socket) -> ok | {error, Reason}
634 listen(Socket, Backlog) -> ok | {error, Reason}
636 Types:
638 Socket = socket()
640 Backlog = integer()
641 Reason = inet:posix() | closed
642 Listen for connections on a socket.
644 number_of() -> integer() >= 0
646 Returns the number of active sockets.
648 open(FD) -> {ok, Socket} | {error, Reason}
650 open(FD, Opts) -> {ok, Socket} | {error, Reason}
652 Types:
654 FD = integer()
656 Opts =
657 #{domain => domain(),
658 type => type(),
659 protocol => protocol(),
660 dup => boolean(),
661 debug => boolean(),
662 use_registry => boolean()}
663 Socket = socket()
664 Reason = errcode()
665 Create an endpoint (socket) for communication based on an al‐
667 ready existing file descriptor. The function attempts to re‐
668 trieve domain, type and protocol from the system. This is how‐
669 ever not possible on all platforms, and in those cases it ex‐
670 pects it in Opts.
671 The Opts argument is intended for providing extra information
673 for the open call:
674 dup: boolean():
676 Shall the provided descriptor be duplicated (dup) or not.
677 Defaults to true.
678 debug: boolean():
680 Enable or disable debug during the open call.
681 Defaults to false.
682 domain: socket:domain():
684 Which domain is the descriptor of.
685 type: socket:type():
687 Which type is the descriptor of.
688 protocol: socket:protocol():
690 Which protocol is the descriptor of.
691 use_registry: boolean():
693 Enable or disable use of the socket registry for this
694 socket. This overrides the global value.
695 Defaults to the global value, see use_registry/1.
696 Note:
698 This function should be used with care!
699 On some platforms its necessary to provide the protocol as its
701 impossible to retrieve it.
702 open(Domain, Type) -> {ok, Socket} | {error, Reason}
705 open(Domain, Type, Protocol) -> {ok, Socket} | {error, Reason}
707 open(Domain, Type, Protocol, Opts) ->
709 {ok, Socket} | {error, Reason}
710 Types:
712 Domain = domain()
714 Type = type()
715 Protocol = default | protocol()
716 Opts =
717 #{netns => string(),
718 debug => boolean(),
719 use_registry => boolean()}
720 Socket = socket()
721 Reason = errcode()
722 Creates an endpoint (socket) for communication.
724 For some types there is a default protocol, indicated by de‐
726 fault, which it may be possible to specify. And for Domain = lo‐
727 cal, if a protocol is pecified, it must be default.
728 The Opts argument is intended for "other" options. The supported
730 option(s) are described below:
731 netns: string():
733 Used to set the network namespace during the open call. Only
734 supported on the Linux platform.
735 debug: boolean():
737 Enable or disable debug during the open call.
738 Defaults to false.
739 use_registry: boolean():
741 Enable or disable use of the socket registry for this
742 socket. This overrides the global value.
743 Defaults to the global value, see use_registry/1.
744 Note:
746 It may not be possible to specify the default protocol (except
747 when Domain = local). We need to be able to retreive the result‐
748 ing protocol, which is not possble on all platforms.
749 peername(Socket) -> {ok, SockAddr} | {error, Reason}
752 Types:
754 Socket = socket()
756 SockAddr = sockaddr()
757 Reason = inet:posix() | closed
758 Returns the address of the peer connected to the socket.
760 recv(Socket) -> {ok, Data} | {error, Reason}
762 recv(Socket, Length) -> {ok, Data} | {error, Reason}
764 recv(Socket, Length, Flags) -> {ok, Data} | {error, Reason}
766 recv(Socket, Length, Timeout) -> {ok, Data} | {error, Reason}
768 recv(Socket, Length, Flags, Timeout) ->
770 {ok, Data} | {error, Reason}
771 Types:
773 Socket = socket()
775 Length = integer() >= 0
776 Flags = recv_flags()
777 Timeout = timeout()
778 Data = binary()
779 Reason =
780 errcode() |
781 closed | timeout |
782 {errcode() | closed | timeout, Data :: binary()}
783 Receive a message from a socket.
785 There is a special case for the argument Length. If it is set to
787 zero (0), it means "give me everything you currently have".
788 recv(Socket, Length, Timeout :: nowait) ->
790 {ok, Data} |
791 {ok, {Data, SelectInfo}} |
792 {select, SelectInfo} |
793 {error, Reason}
794 recv(Socket, Length, Flags, Timeout :: nowait) ->
796 {ok, Data} |
797 {ok, {Data, SelectInfo}} |
798 {select, SelectInfo} |
799 {error, Reason}
800 Types:
802 Socket = socket()
804 Length = integer() >= 0
805 Flags = recv_flags()
806 Data = binary()
807 SelectInfo = select_info()
808 Reason =
809 errcode() | closed | {errcode() | closed, Data :: bi‐
810 nary()}
811 Receive a message from a socket.
813 There is a special case for the argument Length. If it is set to
815 zero (0), it means "give me everything you currently have".
816 In the case when there is no data waiting, the function will re‐
818 turn with the SelectInfo. The caller can then await a select
819 message, {'$socket', Socket, select, Info} (where Info is the
820 ref field from the SelectInfo), when data has arrived (a subse‐
821 quent call to recv will then return the data).
822 Note that if a length (> 0) is specified, and only part of that
824 amount of data is available, the function will return with that
825 data and the SelectInfo (if the caller don't want to wait for
826 the remaining data, it must immediately call the cancel/2 func‐
827 tion.)
828 recvfrom(Socket) -> {ok, {Source, Data}} | {error, Reason}
830 recvfrom(Socket, BufSz) -> {ok, {Source, Data}} | {error, Reason}
832 recvfrom(Socket, Flags, Timeout) ->
834 {ok, {Source, Data}} | {error, Reason}
835 recvfrom(Socket, BufSz, Flags) ->
837 {ok, {Source, Data}} | {error, Reason}
838 recvfrom(Socket, BufSz, Timeout) ->
840 {ok, {Source, Data}} | {error, Reason}
841 recvfrom(Socket, BufSz, Flags, Timeout) ->
843 {ok, {Source, Data}} | {error, Reason}
844 Types:
846 Socket = socket()
848 BufSz = integer() >= 0
849 Flags = recv_flags()
850 Timeout = timeout()
851 Source = sockaddr() | undefined
852 Data = binary()
853 Reason = errcode() | closed | timeout
854 Receive a message from a socket.
856 This function reads "messages", which means that regardless of
858 how much we want to read, it returns when we get a message (if
859 the buffer size is too small, the message will be truncated).
860 The BufSz argument basically defines the size of the receive
862 buffer. By setting the value to zero (0), the configured size
863 (setopt with Level = otp and Key = rcvbuf) is used.
864 It may be impossible to know what (buffer) size is appropriate
866 "in advance", and in those cases it may be convenient to use the
867 (recv) 'peek' flag. When this flag is provided, the message is
868 *not* "consumed" from the underlying buffers, so another
869 recvfrom call is needed, possibly with a then adjusted buffer
870 size.
871 recvfrom(Socket, Flags, Timeout :: nowait) ->
873 {ok, {Source, Data}} |
874 {select, SelectInfo} |
875 {error, Reason}
876 recvfrom(Socket, BufSz, Timeout :: nowait) ->
878 {ok, {Source, Data}} |
879 {select, SelectInfo} |
880 {error, Reason}
881 recvfrom(Socket, BufSz, Flags, Timeout :: nowait) ->
883 {ok, {Source, Data}} |
884 {select, SelectInfo} |
885 {error, Reason}
886 Types:
888 Socket = socket()
890 BufSz = integer() >= 0
891 Flags = recv_flags()
892 Source = sockaddr() | undefined
893 Data = binary()
894 SelectInfo = select_info()
895 Reason = errcode() | closed
896 Receive a message from a socket.
898 This function reads "messages", which means that regardless of
900 how much we want to read, it returns when we get a message (if
901 the buffer size is too small, the message will be truncated).
902 The BufSz argument basically defines the size of the receive
904 buffer. By setting the value to zero (0), the configured size
905 (setopt with Level = otp and Key = rcvbuf) is used.
906 It may be impossible to know what (buffer) size is appropriate
908 "in advance", and in those cases it may be convenient to use the
909 (recv) 'peek' flag. When this flag is provided, the message is
910 *not* "consumed" from the underlying buffers, so another
911 recvfrom call is needed, possibly with a then adjusted buffer
912 size.
913 In the case when there is no data waiting, the function will re‐
915 turn with the SelectInfo. The caller can then await a select
916 message, {'$socket', Socket, select, Info} (where Info is the
917 ref field from the SelectInfo), when data has arrived (a subse‐
918 quent call to recvfrom will then return the data).
919 recvmsg(Socket) -> {ok, MsgHdr} | {error, Reason}
921 recvmsg(Socket, Flags) -> {ok, MsgHdr} | {error, Reason}
923 recvmsg(Socket, Timeout) -> {ok, MsgHdr} | {error, Reason}
925 recvmsg(Socket, Flags, Timeout) -> {ok, MsgHdr} | {error, Reason}
927 recvmsg(Socket, BufSz, CtrlSz) -> {ok, MsgHdr} | {error, Reason}
929 recvmsg(Socket, BufSz, CtrlSz, Flags, Timeout) ->
931 {ok, MsgHdr} | {error, Reason}
932 Types:
934 Socket = socket()
936 BufSz = CtrlSz = integer() >= 0
937 Flags = recv_flags()
938 Timeout = timeout()
939 MsgHdr = msghdr()
940 Reason = errcode() | closed | timeout
941 Receive a message from a socket.
943 This function reads "messages", which means that regardless of
945 how much we want to read, it returns when we get a message.
946 The message will be delivered in the form of a msghdr(), which
948 may contain the source address (if socket not connected), a list
949 of cmsghdr_recv() (depends on what socket options have been set
950 and what the protocol and platform supports) and also a set of
951 flags, providing further info about the read.
952 The BufSz argument basically defines the size of the receive
954 buffer. By setting the value to zero (0), the configured size
955 (setopt with Level = otp and Key = rcvbuf) is used.
956 The CtrlSz argument basically defines the size of the receive
958 buffer for the control messages. By setting the value to zero
959 (0), the configured size (setopt with Level = otp) is used.
960 It may be impossible to know what (buffer) size is appropriate
962 "in advance", and in those cases it may be convenient to use the
963 (recv) 'peek' flag. When this flag is provided, the message is
964 *not* "consumed" from the underlying buffers, so another recvmsg
965 call is needed, possibly with a then adjusted buffer size.
966 recvmsg(Socket, Timeout :: nowait) ->
968 {ok, MsgHdr} | {select, SelectInfo} | {error, Reason}
969 recvmsg(Socket, Flags, Timeout :: nowait) ->
971 {ok, MsgHdr} | {select, SelectInfo} | {error, Reason}
972 recvmsg(Socket, BufSz, CtrlSz, Flags, Timeout :: nowait) ->
974 {ok, MsgHdr} | {select, SelectInfo} | {error, Reason}
975 Types:
977 Socket = socket()
979 BufSz = CtrlSz = integer() >= 0
980 Flags = recv_flags()
981 MsgHdr = msghdr()
982 SelectInfo = select_info()
983 Reason = errcode() | closed
984 Receive a message from a socket.
986 This function reads "messages", which means that regardless of
988 how much we want to read, it returns when we get a message.
989 The message will be delivered in the form of a msghdr(), which
991 may contain the source address (if socket not connected), a list
992 of cmsghdr_recv() (depends on what socket options have been set
993 and what the protocol and platform supports) and also a set of
994 flags, providing further info about the read.
995 The BufSz argument basically defines the size of the receive
997 buffer. By setting the value to zero (0), the configured size
998 (setopt with Level = otp and Key = rcvbuf) is used.
999 The CtrlSz argument basically defines the size of the receive
1001 buffer for the control messages. By setting the value to zero
1002 (0), the configured size (setopt with Level = otp) is used.
1003 It may be impossible to know what (buffer) size is appropriate
1005 "in advance", and in those cases it may be convenient to use the
1006 (recv) 'peek' flag. When this flag is provided, the message is
1007 *not* "consumed" from the underlying buffers, so another recvmsg
1008 call is needed, possibly with a then adjusted buffer size.
1009 In the case when there is no data waiting, the function will re‐
1011 turn with the SelectInfo. The caller can then await a select
1012 message, {'$socket', Socket, select, Info} (where Info is the
1013 ref field from the SelectInfo), when data has arrived (a subse‐
1014 quent call to recvmsg will then return the data).
1015 send(Socket, Data) -> ok | {error, Reason}
1017 send(Socket, Data, Flags) -> ok | {error, Reason}
1019 send(Socket, Data, Timeout) -> ok | {error, Reason}
1021 send(Socket, Data, Flags, Timeout) -> ok | {error, Reason}
1023 Types:
1025 Socket = socket()
1027 Data = iodata()
1028 Flags = send_flags()
1029 Timeout = timeout()
1030 Reason =
1031 {errcode() | closed | timeout, Remaining :: integer() >=
1032 1}
1033 Send a message on a connected socket.
1035 send(Socket, Data, Timeout :: nowait) ->
1037 ok |
1038 {ok, {binary(), SelectInfo}} |
1039 {select, SelectInfo} |
1040 {ok, {RestData, SelectInfo}} |
1041 {error, Reason}
1042 send(Socket, Data, Flags, Timeout :: nowait) ->
1044 ok |
1045 {select, SelectInfo} |
1046 {ok, {RestData, SelectInfo}} |
1047 {error, Reason}
1048 Types:
1050 Socket = socket()
1052 Data = iodata()
1053 Flags = send_flags()
1054 RestData = binary()
1055 SelectInfo = select_info()
1056 Reason = {errcode() | closed, Remaining :: integer() >= 1}
1057 Send a message on a connected socket.
1059 In the case when there is no room in the (system-) buffers, the
1061 function will return with the SelectInfo. The caller can then
1062 await a select message, {'$socket', Socket, select, Info} (where
1063 Info is the ref field from the SelectInfo), when there is room
1064 for more data (a subsequent call to send will then send the
1065 data).
1066 Note that if not all the data was sent, the function will return
1068 with the remaining data and the SelectInfo (if the caller don't
1069 want to wait to be able to send the rest, it should immediately
1070 call the cancel/2 function.)
1071 sendmsg(Socket, MsgHdr) -> ok | {ok, Remaining} | {error, Reason}
1073 sendmsg(Socket, MsgHdr, Flags) -> ok | {error, Reason}
1075 sendmsg(Socket, MsgHdr, Timeout) -> ok | {error, Reason}
1077 sendmsg(Socket, MsgHdr, Flags, Timeout) ->
1079 ok | {ok, Remaining} | {error, Reason}
1080 Types:
1082 Socket = socket()
1084 MsgHdr = msghdr()
1085 Flags = send_flags()
1086 Timeout = timeout()
1087 Remaining = erlang:iovec()
1088 Reason = errcode() | closed | timeout
1089 Send a message on a socket. The destination, if needed (socket
1091 not connected) is provided in the MsgHdr, which also contains
1092 the message to send, The MsgHdr may also contain an list of op‐
1093 tional cmsghdr_send() (depends on what the protocol and platform
1094 supports).
1095 Unlike the send function, this one sends one message. This means
1097 that if, for whatever reason, its not possible to send the mes‐
1098 sage in one go, the function will instead return with the re‐
1099 maining data ({ok, Remaining}). Thereby leaving it up to the
1100 caller to decide what to do (retry with the remaining data of
1101 give up).
1102 sendmsg(Socket, MsgHdr, Timeout :: nowait) ->
1104 ok | {ok, Remaining} | {error, Reason}
1105 sendmsg(Socket, MsgHdr, Flags, Timeout :: nowait) ->
1107 ok | {ok, Remaining} | {error, Reason}
1108 Types:
1110 Socket = socket()
1112 MsgHdr = msghdr()
1113 Flags = send_flags()
1114 Remaining = erlang:iovec()
1115 Reason = errcode() | closed
1116 Send a message on a socket. The destination, if needed (socket
1118 not connected) is provided in the MsgHdr, which also contains
1119 the message to send, The MsgHdr may also contain an list of op‐
1120 tional cmsghdr_send() (depends on what the protocol and platform
1121 supports).
1122 Unlike the send function, this one sends one message. This means
1124 that if, for whatever reason, its not possible to send the mes‐
1125 sage in one go, the function will instead return with the re‐
1126 maining data ({ok, Remaining}). Thereby leaving it up to the
1127 caller to decide what to do (retry with the remaining data of
1128 give up).
1129 In the case when there is no room in the (system-) buffers, the
1131 function will return with the SelectInfo. The caller can then
1132 await a select message, {'$socket', Socket, select, Info} (where
1133 Info is the ref field from the SelectInfo), when there is room
1134 for more data (a subsequent call to sendmsg will then send the
1135 data).
1136 sendto(Socket, Data, Dest) -> ok | {error, Reason}
1138 sendto(Socket, Data, Dest, Flags) -> ok | {error, Reason}
1140 sendto(Socket, Data, Dest, Timeout) -> ok | {error, Reason}
1142 sendto(Socket, Data, Dest, Flags, Timeout) -> ok | {error, Reason}
1144 Types:
1146 Socket = socket()
1148 Data = binary()
1149 Dest = sockaddr()
1150 Flags = send_flags()
1151 Timeout = timeout()
1152 Reason =
1153 {errcode() | closed | timeout, Remaining :: integer() >=
1154 1}
1155 Send a message on a socket, to the specified destination.
1157 sendto(Socket, Data, Dest, Timeout :: nowait) ->
1159 ok | {select, SelectInfo} | {error, Reason}
1160 sendto(Socket, Data, Dest, Flags, Timeout :: nowait) ->
1162 ok |
1163 {ok, {binary(), SelectInfo}} |
1164 {select, SelectInfo} |
1165 {error, Reason}
1166 Types:
1168 Socket = socket()
1170 Data = binary()
1171 Dest = sockaddr()
1172 Flags = send_flags()
1173 SelectInfo = select_info()
1174 Reason = {errcode() | closed, Remaining :: integer() >= 1}
1175 Send a message on a socket, to the specified destination.
1177 In the case when there is no room in the (system-) buffers, the
1179 function will return with the SelectInfo. The caller can then
1180 await a select message, {'$socket', Socket, select, Info} (where
1181 Info is the ref field from the SelectInfo), when there is room
1182 for more data (a subsequent call to sendto will then send the
1183 data).
1184 setopt(Socket, Level :: otp, Key :: otp_socket_option(), Value) ->
1186 ok | {error, Reason}
1187 setopt(Socket, Level :: socket, Key :: socket_option(), Value) ->
1189 ok | {error, Reason}
1190 setopt(Socket, Level :: ip, Key :: ip_socket_option(), Value) ->
1192 ok | {error, Reason}
1193 setopt(Socket, Level :: ipv6, Key :: ipv6_socket_option(), Value) ->
1195 ok | {error, Reason}
1196 setopt(Socket, Level :: tcp, Key :: tcp_socket_option(), Value) ->
1198 ok | {error, Reason}
1199 setopt(Socket, Level :: udp, Key :: udp_socket_option(), Value) ->
1201 ok | {error, Reason}
1202 setopt(Socket, Level :: sctp, Key :: sctp_socket_option(), Value) ->
1204 ok | {error, Reason}
1205 setopt(Socket, Level, Key, Value) -> ok | {error, Reason}
1207 Types:
1209 Socket = socket()
1211 Level = Key = integer() >= 0
1212 Value = binary()
1213 Reason = inet:posix() | closed
1214 Set an option on a socket.
1216 What options are valid depend both on Level and on what kind of
1218 socket it is (domain, type and protocol).
1219 See the socket options chapter of the users guide for more info.
1221 Note:
1223 Not all options are valid on all platforms. That is, even if
1224 "we" support an option, that does not mean that the underlying
1225 OS does.
1226 Note:
1229 Sockets are set 'non-blocking' when created, so this option is
1230 *not* available (as it would adversely effect the Erlang VM to
1231 set a socket 'blocking').
1232 setopt(Socket, Level, Key, Value) -> ok | {error, Reason}
1235 Types:
1237 Socket = socket()
1239 Level = Key = integer() >= 0
1240 Value = binary()
1241 Reason = inet:posix() | closed
1242 Set options on a socket.
1244 When specifying Level as an integer, and therefor using "native
1246 mode", it is *currently* up to the caller to know how to encode
1247 the Value.
1248 For more info, see setopt above.
1250 shutdown(Socket, How) -> ok | {error, Reason}
1252 Types:
1254 Socket = socket()
1256 How = shutdown_how()
1257 Reason = inet:posix() | closed
1258 Shut down all or part of a full-duplex connection.
1260 sockname(Socket) -> {ok, SockAddr} | {error, Reason}
1262 Types:
1264 Socket = socket()
1266 SockAddr = sockaddr()
1267 Reason = inet:posix() | closed
1268 Returns the current address to which the socket is bound.
1270 supports() -> Supports
1272 supports(Key1 :: options) -> SupportsOptions
1273 supports(Key1 :: send_flags) -> SupportsSendFlags
1274 supports(Key1 :: recv_flags) -> SupportsRecvFlags
1275 supports(Key1 :: options, Key2 :: socket) -> SupportsOptionsSocket
1276 supports(Key1 :: options, Key2 :: ip) -> SupportsOptionsIP
1277 supports(Key1 :: options, Key2 :: ipv6) -> SupportsOptionsIPv6
1278 supports(Key1 :: options, Key2 :: tcp) -> SupportsOptionsTCP
1279 supports(Key1 :: options, Key2 :: udp) -> SupportsOptionsUDP
1280 supports(Key1 :: options, Key2 :: sctp) -> SupportsOptionsSCTP
1281 Types:
1283 Supports :: [{Feature, boolean()} | {send_flags, Support‐
1285 sSendFlags} | {recv_flags, SupportsRecvFlags} | {options,
1286 SupportsOptions}]
1287 Feature :: sctp | ipv6 | local | netns
1288 SupportsSendFlags :: [{send_flag(), boolean()}]
1289 SupportsRecvFlags :: [{recv_flag(), boolean()}]
1290 SupportsOptions :: [{socket, SupportsOptionsSocket} | {ip,
1291 SupportsOptionsIP} | {ipv6, SupportsOptionsIPv6} | {tcp, Sup‐
1292 portsOptionsTCP} | {udp, SupportsOptionsUDP} | {sctp, Sup‐
1293 portsOptionsSCTP}]
1294 SupportsOptionsSocket :: [{socket_option(), boolean()}]
1295 SupportsOptionsIP :: [{ip_socket_option(), boolean()}]
1296 SupportsOptionsIPv6 :: [{ipv6_socket_option(), boolean()}]
1297 SupportsOptionsTCP :: [{tcp_socket_option(), boolean()}]
1298 SupportsOptionsUDP :: [{udp_socket_option(), boolean()}]
1299 SupportsOptionsSCTP :: [{sctp_socket_option(), boolean()}]
1300 This function retreives information about what the platform sup‐
1302 ports, such as if SCTP is supported, or which socket options are
1303 supported.
1304 For keys other than the known the empty list is returned, Note
1306 that in a future version or on a different platform there might
1307 be more supported items.
1308 is_supported(Key1 :: sctp | ipv6 | local | netns) -> boolean()
1310 is_supported(Key1 :: send_flags, Key2 :: SendFlag) -> boolean()
1311 is_supported(Key1 :: recv_flags, Key2 :: RecvFlag) -> boolean()
1312 is_supported(Key1 :: options, Key2 :: socket, Key3 :: SocketOption) ->
1313 boolean()
1314 is_supported(Key1 :: options, Key2 :: ip, Key3 :: IPSocketOption) ->
1315 boolean()
1316 is_supported(Key1 :: options, Key2 :: ipv6, Key3 :: IPv6SocketOption)
1317 -> boolean()
1318 is_supported(Key1 :: options, Key2 :: tcp, Key3 :: TCPSocketOption) ->
1319 boolean()
1320 is_supported(Key1 :: options, Key2 :: udp, Key3 :: UDPSocketOption) ->
1321 boolean()
1322 is_supported(Key1 :: options, Key2 :: sctp, Key3 :: SCTPSocketOption)
1323 -> boolean()
1324 Types:
1326 SocketOption :: socket_option()
1328 IPSocketOption :: ip_socket_option()
1329 IPv6SocketOption :: ipv6_socket_option()
1330 TCPSocketOption :: tcp_socket_option()
1331 UDPSocketOption :: udp_socket_option()
1332 SCTPSocketOption :: sctp_socket_option()
1333 This function retreives information about what the platform sup‐
1335 ports, such as if SCTP is supported, or which socket options are
1336 supported.
1337 For keys other than the known false is returned. Note that in a
1339 future version or on a different platform there might be more
1340 supported items.
1341 use_registry(D :: boolean()) -> ok
1343 Globally change if the socket registry is to be used or not.
1345 Note that its still possible to override this explicitly when
1346 creating an individual sockets, see open/2 or open/4 for more
1347 info (use the Extra argument).
1348 which_sockets() -> [socket()]
1350 which_sockets(FilterRule) -> [socket()]
1352 Types:
1354 FilterRule =
1356 inet | inet6 | stream | dgram | seqpacket | sctp | tcp |
1357 udp |
1358 pid() |
1359 fun((socket_info()) -> boolean())
1360 Returns a list of all sockets, according to the filter rule.
1362 There are several pre-made filter rule(s) and one general:
1364 inet | inet6:
1366 Selection based on the domain of the socket.
1367 Only a subset is valid.
1368 stream | dgram | seqpacket:
1370 Selection based on the type of the socket.
1371 Only a subset is valid.
1372 sctp | tcp | udp:
1374 Selection based on the protocol of the socket.
1375 Only a subset is valid.
1376 pid():
1378 Selection base on which sockets has this pid as Controlling
1379 Process.
1380 fun((socket_info()) -> boolean()):
1382 The general filter rule.
1383 A fun that takes the socket info and returns a boolean()
1384 (true if the socket sould be included and false if should
1385 not).
1386
1388 client(Addr, SAddr, SPort) ->
1389 {ok, Sock} = socket:open(inet, stream, tcp),
1390 {ok, _} = socket:bind(Sock, #{family => inet,
1391 addr => Addr}),
1392 ok = socket:connect(Sock, #{family => inet,
1393 addr => SAddr,
1394 port => SPort}),
1395 Msg = list_to_binary("hello"),
1396 ok = socket:send(Sock, Msg),
1397 ok = socket:shutdown(Sock, write),
1398 {ok, Msg} = socket:recv(Sock),
1399 ok = socket:close(Sock).
1400 server(Addr, Port) ->
1402 {ok, LSock} = socket:open(inet, stream, tcp),
1403 {ok, _} = socket:bind(LSock, #{family => inet,
1404 port => Port,
1405 addr => Addr}),
1406 ok = socket:listen(LSock),
1407 {ok, Sock} = socket:accept(LSock),
1408 {ok, Msg} = socket:recv(Sock),
1409 ok = socket:send(Sock, Msg),
1410 ok = socket:shutdown(Sock, write),
1411 ok = socket:close(Sock),
1412 ok = socket:close(LSock).
1413Ericsson AB kernel 7.3.1.1 socket(3)