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
11 reciving 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,
22 SelectInfo} (SelectInfo contains the SelectRef). When data eventually
23 arrives 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
28 expect 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/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() = [{socket_counter(), integer() >= 0}]
74 socket_counter() =
76 read_byte | read_fails | read_pkg | read_pkg_max |
77 read_tries | read_waits | write_byte | write_fails |
78 write_pkg | write_pkg_max | write_tries | write_waits |
79 acc_success | acc_fails | acc_tries | acc_waits
80 socket_info() =
82 #{domain := domain(),
83 type := type(),
84 protocol := protocol(),
85 ctrl := pid(),
86 counters := socket_counters(),
87 num_readers := integer() >= 0,
88 num_writers := integer() >= 0,
89 num_acceptors := integer() >= 0,
90 writable := boolean(),
91 readable := boolean()}
92 ip4_address() = {0..255, 0..255, 0..255, 0..255}
94 ip6_address() =
96 {0..65535,
97 0..65535,
98 0..65535,
99 0..65535,
100 0..65535,
101 0..65535,
102 0..65535,
103 0..65535}
104 ip_address() = ip4_address() | ip6_address()
106 sockaddr() =
108 sockaddr_in4() |
109 sockaddr_in6() |
110 sockaddr_un() |
111 sockaddr_ll()
112 sockaddr_in4() =
114 #{family := inet,
115 port := port_number(),
116 addr := any | broadcast | loopback | ip4_address()}
117 sockaddr_in6() =
119 #{family := inet6,
120 port := port_number(),
121 addr := any | loopback | ip6_address(),
122 flowinfo := in6_flow_info(),
123 scope_id := in6_scope_id()}
124 sockaddr_un() = #{family := local, path := binary() | string()}
126 sockaddr_ll() =
128 #{family := packet,
129 protocol := integer() >= 0,
130 ifindex := integer(),
131 pkttype := packet_type(),
132 hatype := integer() >= 0,
133 addr := binary()}
134 packet_type() =
136 host | broadcast | multicast | otherhost | outgoing |
137 loopback | user | kernel | fastroute |
138 integer() >= 0
139 port_number() = 0..65535
141 in6_flow_info() = uint20()
143 in6_scope_id() = uint32()
145 send_flags() = [send_flag()]
147 send_flag() = confirm | dontroute | eor | more | nosignal | oob
149 recv_flags() = [recv_flag()]
151 recv_flag() = cmsg_cloexec | errqueue | oob | peek | trunc
153 shutdown_how() = read | write | read_write
155 sockopt_level() =
157 otp | socket | ip | ipv6 | tcp | udp | sctp |
158 integer() >= 0
159 otp_socket_option() =
161 debug | iow | controlling_process | rcvbuf | rcvctrlbuf |
162 sndctrlbuf | fd
163 socket_option() =
165 acceptconn | acceptfilter | bindtodevice | broadcast |
166 busy_poll | debug | domain | dontroute | error | keepalive |
167 linger | mark | oobinline | passcred | peek_off | peercred |
168 priority | protocol | rcvbuf | rcvbufforce | rcvlowat |
169 rcvtimeo | reuseaddr | reuseport | rxq_ovfl | setfib |
170 sndbuf | sndbufforce | sndlowat | sndtimeo | timestamp | type
171 ip_socket_option() =
173 add_membership | add_source_membership | block_source |
174 dontfrag | drop_membership | drop_source_membership |
175 freebind | hdrincl | minttl | msfilter | mtu | mtu_discover |
176 multicast_all | multicast_if | multicast_loop |
177 multicast_ttl | nodefrag | options | pktinfo | recverr |
178 recvif | recvdstaddr | recvopts | recvorigdstaddr | recvtos |
179 recvttl | retopts | router_alert | sndsrcaddr | tos |
180 transparent | ttl | unblock_source
181 ipv6_socket_option() =
183 addrform | add_membership | authhdr | auth_level | checksum |
184 drop_membership | dstopts | esp_trans_level |
185 esp_network_level | faith | flowinfo | hopopts |
186 ipcomp_level | join_group | leave_group | mtu | mtu_discover |
187 multicast_hops | multicast_if | multicast_loop | portrange |
188 pktoptions | recverr | recvhoplimit | hoplimit | recvpktinfo |
189 pktinfo | recvtclass | router_alert | rthdr | tclass |
190 unicast_hops | use_min_mtu | v6only
191 tcp_socket_option() =
193 congestion | cork | info | keepcnt | keepidle | keepintvl |
194 maxseg | md5sig | nodelay | noopt | nopush | syncnt |
195 user_timeout
196 udp_socket_option() = cork
198 sctp_socket_option() =
200 adaption_layer | associnfo | auth_active_key | auth_asconf |
201 auth_chunk | auth_key | auth_delete_key | autoclose |
202 context | default_send_params | delayed_ack_time |
203 disable_fragments | hmac_ident | events | explicit_eor |
204 fragment_interleave | get_peer_addr_info | initmsg |
205 i_want_mapped_v4_addr | local_auth_chunks | maxseg |
206 maxburst | nodelay | partial_delivery_point |
207 peer_addr_params | peer_auth_chunks | primary_addr |
208 reset_streams | rtoinfo | set_peer_primary_addr | status |
209 use_ext_recvinfo
210 timeval() = #{sec := integer(), usec := integer()}
212 ip_tos() =
214 lowdelay | throughput | reliability | mincost | integer()
215 ip_mreq() =
217 #{multiaddr := ip4_address(),
218 interface := any | ip4_address()}
219 ip_mreq_source() =
221 #{multiaddr := ip4_address(),
222 interface := ip4_address(),
223 sourceaddr := ip4_address()}
224 ip_pmtudisc() = want | dont | do | probe
226 ip_msfilter_mode() = include | exclude
228 ip_msfilter() =
230 #{multiaddr := ip4_address(),
231 interface := ip4_address(),
232 mode := ip_msfilter_mode(),
233 slist := [ip4_address()]}
234 ip_pktinfo() =
236 #{ifindex := integer() >= 0,
237 spec_dst := ip4_address(),
238 addr := ip4_address()}
239 ipv6_mreq() =
241 #{multiaddr := ip6_address(), interface := integer() >= 0}
242 ipv6_pmtudisc() = ip_pmtudisc()
244 ipv6_pktinfo() = #{addr := ip6_address(), ifindex := integer()}
246 sctp_assoc_id() = int32()
248 sctp_sndrcvinfo() =
250 #{stream := uint16(),
251 ssn := uint16(),
252 flags := uint16(),
253 ppid := uint16(),
254 context := uint16(),
255 timetolive := uint16(),
256 tsn := uint16(),
257 cumtsn := uint16(),
258 assoc_id := sctp_assoc_id()}
259 sctp_event_subscribe() =
261 #{data_in := boolean(),
262 association := boolean(),
263 address := boolean(),
264 send_failure := boolean(),
265 peer_error := boolean(),
266 shutdown := boolean(),
267 partial_delivery := boolean(),
268 adaptation_layer := boolean(),
269 authentication := boolean(),
270 sender_dry := boolean()}
271 sctp_assocparams() =
273 #{assoc_id := sctp_assoc_id(),
274 max_rxt := uint16(),
275 num_peer_dests := uint16(),
276 peer_rwnd := uint32(),
277 local_rwnd := uint32(),
278 cookie_life := uint32()}
279 sctp_initmsg() =
281 #{num_outstreams := uint16(),
282 max_instreams := uint16(),
283 max_attempts := uint16(),
284 max_init_timeo := uint16()}
285 sctp_rtoinfo() =
287 #{assoc_id := sctp_assoc_id(),
288 initial := uint32(),
289 max := uint32(),
290 min := uint32()}
291 msghdr_flag() = ctrunc | eor | errqueue | oob | trunc
293 msghdr_flags() = [msghdr_flag()]
295 msghdr() =
297 #{addr := sockaddr(),
298 iov := [binary()],
299 ctrl := [cmsghdr_recv()] | [cmsghdr_send()],
300 flags := msghdr_flags()}
301 cmsghdr_level() = socket | ip | ipv6 | integer()
303 cmsghdr_type() =
305 credentials | hoplevel | origdstaddr | pktinfo | recvtos |
306 rights | timestamp | tos | ttl |
307 integer()
308 cmsghdr_recv() =
310 #{level := socket, type := timestamp, data := timeval()} |
311 #{level := socket, type := rights, data := binary()} |
312 #{level := socket, type := credentials, data := binary()} |
313 #{level := socket, type := integer(), data := binary()} |
314 #{level := ip, type := tos, data := ip_tos()} |
315 #{level := ip, type := recvtos, data := ip_tos()} |
316 #{level := ip, type := ttl, data := integer()} |
317 #{level := ip, type := recvttl, data := integer()} |
318 #{level := ip, type := pktinfo, data := ip_pktinfo()} |
319 #{level := ip, type := origdstaddr, data := sockaddr_in4()} |
320 #{level := ip,
321 type := recverr,
322 data := extended_err() | binary()} |
323 #{level := ip, type := integer(), data := binary()} |
324 #{level := ipv6, type := hoplevel, data := integer()} |
325 #{level := ipv6, type := pktinfo, data := ipv6_pktinfo()} |
326 #{level := ipv6,
327 type := recverr,
328 data := extended_err() | binary()} |
329 #{level := ipv6, type := tclass, data := integer()} |
330 #{level := ipv6, type := integer(), data := binary()} |
331 #{level := integer(), type := integer(), data := binary()}
332 cmsghdr_send() =
334 #{level := socket, type := timestamp, data := binary()} |
335 #{level := socket, type := rights, data := binary()} |
336 #{level := socket, type := credentials, data := binary()} |
337 #{level := socket, type := integer(), data := binary()} |
338 #{level := ip, type := tos, data := ip_tos() | binary()} |
339 #{level := ip, type := ttl, data := integer() | binary()} |
340 #{level := ip, type := integer(), data := binary()} |
341 #{level := ipv6, type := tclass, data := integer()} |
342 #{level := ipv6, type := integer(), data := binary()} |
343 #{level := udp, type := integer(), data := binary()} |
344 #{level := integer(), type := integer(), data := binary()}
345 icmp_dest_unreach() =
347 net_unreach | host_unreach | port_unreach | frag_needed |
348 net_unknown | host_unknown |
349 uint8()
350 icmpv6_dest_unreach() =
352 noroute | adm_prohibited | not_neighbour | addr_unreach |
353 port_unreach | policy_fail | reject_route |
354 uint8()
355 ee_origin() = none | local | icmp | icmp6 | uint8()
357 extended_err() =
359 #{error := term(),
360 origin := icmp,
361 type := dest_unreach,
362 code := icmp_dest_unreach(),
363 info := uint32(),
364 data := uint32(),
365 offender := undefined | sockaddr()} |
366 #{error := term(),
367 origin := icmp,
368 type := time_exceeded | uint8(),
369 code := uint8(),
370 info := uint32(),
371 data := uint32(),
372 offender := undefined | sockaddr()} |
373 #{error := term(),
374 origin := icmp6,
375 type := dest_unreach,
376 code := icmpv6_dest_unreach(),
377 info := uint32(),
378 data := uint32(),
379 offender := undefined | sockaddr()} |
380 #{error := term(),
381 origin := icmp6,
382 type := pkt_toobig | time_exceeded | uint8(),
383 code := uint8(),
384 info := uint32(),
385 data := uint32(),
386 offender := undefined | sockaddr()} |
387 #{error := term(),
388 origin := ee_origin(),
389 type := uint8(),
390 code := uint8(),
391 info := uint32(),
392 data := uint32(),
393 offender := undefined | sockaddr()}
394 uint8() = 0..255
396 uint16() = 0..65535
398 uint20() = 0..1048575
400 uint32() = 0..4294967295
402 int32() = -2147483648..2147483647
404 supports_options_socket() = [{socket_option(), boolean()}]
406 supports_options_ip() = [{ip_socket_option(), boolean()}]
408 supports_options_ipv6() = [{ipv6_socket_option(), boolean()}]
410 supports_options_tcp() = [{tcp_socket_option(), boolean()}]
412 supports_options_udp() = [{udp_socket_option(), boolean()}]
414 supports_options_sctp() = [{sctp_socket_option(), boolean()}]
416 supports_options() =
418 [{socket, supports_options_socket()} |
419 {ip, supports_options_ip()} |
420 {ipv6, supports_options_ipv6()} |
421 {tcp, supports_options_tcp()} |
422 {udp, supports_options_udp()} |
423 {sctp, supports_options_sctp()}]
424 supports_send_flags() = [{send_flag(), boolean()}]
426 supports_recv_flags() = [{recv_flag(), boolean()}]
428
430 accept(LSocket) -> {ok, Socket} | {error, Reason}
431 accept(LSocket, Timeout) -> {ok, Socket} | {error, Reason}
433 Types:
435 LSocket = socket()
437 Timeout = timeout()
438 Socket = socket()
439 Reason = term()
440 Accept a connection on a socket.
442 This call is used with connection-based socket types (stream or
444 seqpacket). It extracs the first pending connection request for
445 the listen socket and returns the (newly) connected socket.
446 accept(LSocket, Timeout :: nowait) ->
448 {ok, Socket} | {select, SelectInfo} | {error, Reason}
449 Types:
451 LSocket = Socket = socket()
453 SelectInfo = select_info()
454 Reason = term()
455 Accept a connection on a socket.
457 This call is used with connection-based socket types (stream or
459 seqpacket). It extracs the first pending connection request for
460 the listen socket and returns the (newly) connected socket.
461 In the case when there is no connections waiting, the function
463 will return with the SelectInfo. The caller can then await a
464 select message, {'$socket', Socket, select, Info} (where Info is
465 the ref field from the SelectInfo), when a client connects (a
466 subsequent call to accept will then return the socket).
467 bind(Socket, Addr) -> {ok, Port} | {error, Reason}
469 Types:
471 Socket = socket()
473 Addr = any | broadcast | loopback | sockaddr()
474 Port = port_number()
475 Reason = term()
476 Bind a name to a socket.
478 When a socket is created (with open), it has no address assigned
480 to it. bind assigns the address specified by the Addr argument.
481 The rules used for name binding vary between domains.
483 cancel(Socket, SelectInfo) -> ok | {error, Reason}
485 Types:
487 Socket = socket()
489 SelectInfo = select_info()
490 Reason = term()
491 Cancel an asynchronous request.
493 Call this function in order to cancel a previous asynchronous
495 call to, e.g. recv/3.
496 close(Socket) -> ok | {error, Reason}
498 Types:
500 Socket = socket()
502 Reason = term()
503 Closes the socket.
505 Note:
507 Note that for e.g. protocol = tcp, most implementations doing a
508 close does not guarantee that any data sent is delivered to the
509 recipient before the close is detected at the remote side.
510 One way to handle this is to use the shutdown function
512 (socket:shutdown(Socket, write)) to signal that no more data is
513 to be sent and then wait for the read side of the socket to be
514 closed.
515 connect(Socket, SockAddr) -> ok | {error, Reason}
518 connect(Socket, SockAddr, Timeout) -> ok | {error, Reason}
520 Types:
522 Socket = socket()
524 SockAddr = sockaddr()
525 Timeout = timeout()
526 Reason = term()
527 This function connects the socket to the address specied by the
529 SockAddr argument.
530 connect(Socket, SockAddr, Timeout :: nowait) ->
532 ok | {select, SelectInfo} | {error, Reason}
533 Types:
535 Socket = socket()
537 SockAddr = sockaddr()
538 SelectInfo = select_info()
539 Reason = term()
540 This function connects the socket to the address specied by the
542 SockAddr argument.
543 In the case when its not possible to immediately establish a
545 connection, the function will return with the SelectInfo. The
546 caller can then await a select message, {'$socket', Socket,
547 select, Info} (where Info is the ref field from the SelectInfo,
548 a subsequent call to connect will then establish the connec‐
549 tion).
550 getopt(Socket, Level :: otp, Key :: otp_socket_option()) ->
552 {ok, Value} | {error, Reason}
553 getopt(Socket, Level :: socket, Key :: socket_option()) ->
555 {ok, Value} | {error, Reason}
556 getopt(Socket, Level :: ip, Key :: ip_socket_option()) ->
558 {ok, Value} | {error, Reason}
559 getopt(Socket, Level :: ipv6, Key :: ipv6_socket_option()) ->
561 {ok, Value} | {error, Reason}
562 getopt(Socket, Level :: tcp, Key :: tcp_socket_option()) ->
564 {ok, Value} | {error, Reason}
565 getopt(Socket, Level :: udp, Key :: udp_socket_option()) ->
567 {ok, Value} | {error, Reason}
568 getopt(Socket, Level :: sctp, Key :: sctp_socket_option()) ->
570 {ok, Value} | {error, Reason}
571 Types:
573 Socket = socket()
575 Value = Reason = term()
576 Get an option on a socket.
578 What properties are valid depend both on Level and on what kind
580 of socket it is (domain, type and protocol).
581 See the socket options chapter of the users guide for more info.
583 Note:
585 Not all options are valid on all platforms. That is, even if
586 "we" support an option, that does not mean that the underlying
587 OS does.
588 getopt(Socket, Level, Key) -> ok | {ok, Value} | {error, Reason}
591 Types:
593 Socket = socket()
595 Level = integer()
596 Key = {NativeOpt, ValueSize}
597 NativeOpt = integer()
598 ValueSize = int | bool | integer() >= 0
599 Value = Reason = term()
600 Get an option on a socket.
602 When specifying Level as an integer, and therefor using "native
604 mode", it is *currently* up to the caller to know how to inter‐
605 pret the result.
606 For more info, see getopt above.
608 info(Socket) -> socket_info()
610 Types:
612 Socket = socket()
614 Get miscellaneous info about the socket.
616 The function returns a map with each info item as a key-value
618 binding. It reflects the "current" state of the socket.
619 Note:
621 In order to ensure data integrity, mutex'es are taken when
622 needed. So, do not call this function often.
623 listen(Socket) -> ok | {error, Reason}
626 listen(Socket, Backlog) -> ok | {error, Reason}
628 Types:
630 Socket = socket()
632 Backlog = integer() >= 1
633 Reason = term()
634 Listen for connections on a socket.
636 number_of() -> integer() >= 0
638 Returns the number of active sockets.
640 open(Domain, Type) -> {ok, Socket} | {error, Reason}
642 open(Domain, Type, Protocol) -> {ok, Socket} | {error, Reason}
644 open(Domain, Type, Protocol, Extra) ->
646 {ok, Socket} | {error, Reason}
647 Types:
649 Domain = domain()
651 Type = type()
652 Protocol = default | protocol()
653 Extra = map()
654 Socket = socket()
655 Reason = term()
656 Creates an endpoint (socket) for communication.
658 For some types there is a default protocol, indicated by
660 default, which it may be possible to specify. And for Domain =
661 local, if a protocol is pecified, it must be default.
662 The Extra argument is intended for "obscure" options. Currently
664 the only supported option is netns, which is only supported on
665 the linux platform.
666 Note:
668 It may not be possible to specify the default protocol (except
669 when Domain = local). We need to be able to retreive the result‐
670 ing protocol, which is not possble on all platforms.
671 peername(Socket) -> {ok, SockAddr} | {error, Reason}
674 Types:
676 Socket = socket()
678 SockAddr = sockaddr()
679 Reason = term()
680 Returns the address of the peer connected to the socket.
682 recv(Socket) -> {ok, Data} | {error, Reason}
684 recv(Socket, Length) -> {ok, Data} | {error, Reason}
686 recv(Socket, Length, Flags) -> {ok, Data} | {error, Reason}
688 recv(Socket, Length, Timeout) -> {ok, Data} | {error, Reason}
690 recv(Socket, Length, Flags, Timeout) ->
692 {ok, Data} | {error, Reason}
693 Types:
695 Socket = socket()
697 Length = integer() >= 0
698 Flags = recv_flags()
699 Timeout = timeout()
700 Data = binary()
701 Reason = term()
702 Receive a message from a socket.
704 There is a special case for the argument Length. If it is set to
706 zero (0), it means "give me everything you currently have".
707 recv(Socket, Length, Timeout :: nowait) ->
709 {ok, Data} |
710 {select, SelectInfo} |
711 {ok, {Data, SelectInfo}} |
712 {error, Reason}
713 recv(Socket, Length, Flags, Timeout :: nowait) ->
715 {ok, Data} |
716 {select, SelectInfo} |
717 {ok, {Data, SelectInfo}} |
718 {error, Reason}
719 Types:
721 Socket = socket()
723 Length = integer() >= 0
724 Flags = recv_flags()
725 Data = binary()
726 SelectInfo = select_info()
727 Reason = term()
728 Receive a message from a socket.
730 There is a special case for the argument Length. If it is set to
732 zero (0), it means "give me everything you currently have".
733 In the case when there is no data waiting, the function will
735 return with the SelectInfo. The caller can then await a select
736 message, {'$socket', Socket, select, Info} (where Info is the
737 ref field from the SelectInfo), when data has arrived (a subse‐
738 quent call to recv will then return the data).
739 Note that if a length (> 0) is specified, and only part of that
741 amount of data is available, the function will return with that
742 data and the SelectInfo (if the caller don't want to wait for
743 the remaining data, it must immediately call the cancel/2 func‐
744 tion.)
745 recvfrom(Socket) -> {ok, {Source, Data}} | {error, Reason}
747 recvfrom(Socket, BufSz) -> {ok, {Source, Data}} | {error, Reason}
749 recvfrom(Socket, Flags, Timeout) ->
751 {ok, {Source, Data}} | {error, Reason}
752 recvfrom(Socket, BufSz, Flags) ->
754 {ok, {Source, Data}} | {error, Reason}
755 recvfrom(Socket, BufSz, Timeout) ->
757 {ok, {Source, Data}} | {error, Reason}
758 recvfrom(Socket, BufSz, Flags, Timeout) ->
760 {ok, {Source, Data}} | {error, Reason}
761 Types:
763 Socket = socket()
765 BufSz = integer() >= 0
766 Flags = recv_flags()
767 Timeout = timeout()
768 Source = sockaddr() | undefined
769 Data = binary()
770 Reason = term()
771 Receive a message from a socket.
773 This function reads "messages", which means that regardless of
775 how much we want to read, it returns when we get a message (if
776 the buffer size is too small, the message will be truncated).
777 The BufSz argument basically defines the size of the receive
779 buffer. By setting the value to zero (0), the configured size
780 (setopt with Level = otp and Key = rcvbuf) is used.
781 It may be impossible to know what (buffer) size is appropriate
783 "in advance", and in those cases it may be convenient to use the
784 (recv) 'peek' flag. When this flag is provided, the message is
785 *not* "consumed" from the underlying buffers, so another
786 recvfrom call is needed, possibly with a then adjusted buffer
787 size.
788 recvfrom(Socket, Flags, Timeout :: nowait) ->
790 {ok, {Source, Data}} |
791 {select, SelectInfo} |
792 {error, Reason}
793 recvfrom(Socket, BufSz, Timeout :: nowait) ->
795 {ok, {Source, Data}} |
796 {select, SelectInfo} |
797 {error, Reason}
798 recvfrom(Socket, BufSz, Flags, Timeout :: nowait) ->
800 {ok, {Source, Data}} |
801 {select, SelectInfo} |
802 {error, Reason}
803 Types:
805 Socket = socket()
807 BufSz = integer() >= 0
808 Flags = recv_flags()
809 Source = sockaddr() | undefined
810 Data = binary()
811 SelectInfo = select_info()
812 Reason = term()
813 Receive a message from a socket.
815 This function reads "messages", which means that regardless of
817 how much we want to read, it returns when we get a message (if
818 the buffer size is too small, the message will be truncated).
819 The BufSz argument basically defines the size of the receive
821 buffer. By setting the value to zero (0), the configured size
822 (setopt with Level = otp and Key = rcvbuf) is used.
823 It may be impossible to know what (buffer) size is appropriate
825 "in advance", and in those cases it may be convenient to use the
826 (recv) 'peek' flag. When this flag is provided, the message is
827 *not* "consumed" from the underlying buffers, so another
828 recvfrom call is needed, possibly with a then adjusted buffer
829 size.
830 In the case when there is no data waiting, the function will
832 return with the SelectInfo. The caller can then await a select
833 message, {'$socket', Socket, select, Info} (where Info is the
834 ref field from the SelectInfo), when data has arrived (a subse‐
835 quent call to recvfrom will then return the data).
836 recvmsg(Socket) -> {ok, MsgHdr} | {error, Reason}
838 recvmsg(Socket, Flags) -> {ok, MsgHdr} | {error, Reason}
840 recvmsg(Socket, Timeout) -> {ok, MsgHdr} | {error, Reason}
842 recvmsg(Socket, Flags, Timeout) -> {ok, MsgHdr} | {error, Reason}
844 recvmsg(Socket, BufSz, CtrlSz) -> {ok, MsgHdr} | {error, Reason}
846 recvmsg(Socket, BufSz, CtrlSz, Flags, Timeout) ->
848 {ok, MsgHdr} | {error, Reason}
849 Types:
851 Socket = socket()
853 BufSz = CtrlSz = integer() >= 0
854 Flags = recv_flags()
855 Timeout = timeout()
856 MsgHdr = msghdr()
857 Reason = term()
858 Receive a message from a socket.
860 This function reads "messages", which means that regardless of
862 how much we want to read, it returns when we get a message.
863 The message will be delivered in the form of a msghdr(), which
865 may contain the source address (if socket not connected), a list
866 of cmsghdr_recv() (depends on what socket options have been set
867 and what the protocol and platform supports) and also a set of
868 flags, providing further info about the read.
869 The BufSz argument basically defines the size of the receive
871 buffer. By setting the value to zero (0), the configured size
872 (setopt with Level = otp and Key = rcvbuf) is used.
873 The CtrlSz argument basically defines the size of the receive
875 buffer for the control messages. By setting the value to zero
876 (0), the configured size (setopt with Level = otp) is used.
877 It may be impossible to know what (buffer) size is appropriate
879 "in advance", and in those cases it may be convenient to use the
880 (recv) 'peek' flag. When this flag is provided, the message is
881 *not* "consumed" from the underlying buffers, so another recvmsg
882 call is needed, possibly with a then adjusted buffer size.
883 recvmsg(Socket, Timeout :: nowait) ->
885 {ok, MsgHdr} | {select, SelectInfo} | {error, Reason}
886 recvmsg(Socket, Flags, Timeout :: nowait) ->
888 {ok, MsgHdr} | {select, SelectInfo} | {error, Reason}
889 recvmsg(Socket, BufSz, CtrlSz, Flags, Timeout :: nowait) ->
891 {ok, MsgHdr} | {select, SelectInfo} | {error, Reason}
892 Types:
894 Socket = socket()
896 BufSz = CtrlSz = integer() >= 0
897 Flags = recv_flags()
898 MsgHdr = msghdr()
899 SelectInfo = select_info()
900 Reason = term()
901 Receive a message from a socket.
903 This function reads "messages", which means that regardless of
905 how much we want to read, it returns when we get a message.
906 The message will be delivered in the form of a msghdr(), which
908 may contain the source address (if socket not connected), a list
909 of cmsghdr_recv() (depends on what socket options have been set
910 and what the protocol and platform supports) and also a set of
911 flags, providing further info about the read.
912 The BufSz argument basically defines the size of the receive
914 buffer. By setting the value to zero (0), the configured size
915 (setopt with Level = otp and Key = rcvbuf) is used.
916 The CtrlSz argument basically defines the size of the receive
918 buffer for the control messages. By setting the value to zero
919 (0), the configured size (setopt with Level = otp) is used.
920 It may be impossible to know what (buffer) size is appropriate
922 "in advance", and in those cases it may be convenient to use the
923 (recv) 'peek' flag. When this flag is provided, the message is
924 *not* "consumed" from the underlying buffers, so another recvmsg
925 call is needed, possibly with a then adjusted buffer size.
926 In the case when there is no data waiting, the function will
928 return with the SelectInfo. The caller can then await a select
929 message, {'$socket', Socket, select, Info} (where Info is the
930 ref field from the SelectInfo), when data has arrived (a subse‐
931 quent call to recvmsg will then return the data).
932 send(Socket, Data) -> ok | {error, Reason}
934 send(Socket, Data, Flags) -> ok | {error, Reason}
936 send(Socket, Data, Timeout) -> ok | {error, Reason}
938 send(Socket, Data, Flags, Timeout) -> ok | {error, Reason}
940 Types:
942 Socket = socket()
944 Data = iodata()
945 Flags = send_flags()
946 Timeout = timeout()
947 Reason = term()
948 Send a message on a connected socket.
950 send(Socket, Data, Timeout :: nowait) ->
952 ok |
953 {ok, {binary(), SelectInfo}} |
954 {select, SelectInfo} |
955 {ok, {RestData, SelectInfo}} |
956 {error, Reason}
957 send(Socket, Data, Flags, Timeout :: nowait) ->
959 ok |
960 {select, SelectInfo} |
961 {ok, {RestData, SelectInfo}} |
962 {error, Reason}
963 Types:
965 Socket = socket()
967 Data = iodata()
968 Flags = send_flags()
969 RestData = binary()
970 SelectInfo = select_info()
971 Reason = term()
972 Send a message on a connected socket.
974 In the case when there is no room in the (system-) buffers, the
976 function will return with the SelectInfo. The caller can then
977 await a select message, {'$socket', Socket, select, Info} (where
978 Info is the ref field from the SelectInfo), when there is room
979 for more data (a subsequent call to send will then send the
980 data).
981 Note that if not all the data was sent, the function will return
983 with the remaining data and the SelectInfo (if the caller don't
984 want to wait to be able to send the rest, it should immediately
985 call the cancel/2 function.)
986 sendmsg(Socket, MsgHdr) -> ok | {ok, Remaining} | {error, Reason}
988 sendmsg(Socket, MsgHdr, Flags) -> ok | {error, Reason}
990 sendmsg(Socket, MsgHdr, Timeout) -> ok | {error, Reason}
992 sendmsg(Socket, MsgHdr, Flags, Timeout) ->
994 ok | {ok, Remaining} | {error, Reason}
995 Types:
997 Socket = socket()
999 MsgHdr = msghdr()
1000 Flags = send_flags()
1001 Timeout = timeout()
1002 Remaining = erlang:iovec()
1003 Reason = term()
1004 Send a message on a socket. The destination, if needed (socket
1006 not connected) is provided in the MsgHdr, which also contains
1007 the message to send, The MsgHdr may also contain an list of
1008 optional cmsghdr_send() (depends on what the protocol and plat‐
1009 form supports).
1010 Unlike the send function, this one sends one message. This means
1012 that if, for whatever reason, its not possible to send the mes‐
1013 sage in one go, the function will instead return with the
1014 remaining data ({ok, Remaining}). Thereby leaving it up to the
1015 caller to decide what to do (retry with the remaining data of
1016 give up).
1017 sendmsg(Socket, MsgHdr, Timeout :: nowait) ->
1019 ok | {ok, Remaining} | {error, Reason}
1020 sendmsg(Socket, MsgHdr, Flags, Timeout :: nowait) ->
1022 ok | {ok, Remaining} | {error, Reason}
1023 Types:
1025 Socket = socket()
1027 MsgHdr = msghdr()
1028 Flags = send_flags()
1029 Remaining = erlang:iovec()
1030 Reason = term()
1031 Send a message on a socket. The destination, if needed (socket
1033 not connected) is provided in the MsgHdr, which also contains
1034 the message to send, The MsgHdr may also contain an list of
1035 optional cmsghdr_send() (depends on what the protocol and plat‐
1036 form supports).
1037 Unlike the send function, this one sends one message. This means
1039 that if, for whatever reason, its not possible to send the mes‐
1040 sage in one go, the function will instead return with the
1041 remaining data ({ok, Remaining}). Thereby leaving it up to the
1042 caller to decide what to do (retry with the remaining data of
1043 give up).
1044 In the case when there is no room in the (system-) buffers, the
1046 function will return with the SelectInfo. The caller can then
1047 await a select message, {'$socket', Socket, select, Info} (where
1048 Info is the ref field from the SelectInfo), when there is room
1049 for more data (a subsequent call to sendmsg will then send the
1050 data).
1051 sendto(Socket, Data, Dest) -> ok | {error, Reason}
1053 sendto(Socket, Data, Dest, Flags) -> ok | {error, Reason}
1055 sendto(Socket, Data, Dest, Timeout) -> ok | {error, Reason}
1057 sendto(Socket, Data, Dest, Flags, Timeout) -> ok | {error, Reason}
1059 Types:
1061 Socket = socket()
1063 Data = binary()
1064 Dest = sockaddr()
1065 Flags = send_flags()
1066 Timeout = timeout()
1067 Reason = term()
1068 Send a message on a socket, to the specified destination.
1070 sendto(Socket, Data, Dest, Timeout :: nowait) ->
1072 ok | {select, SelectInfo} | {error, Reason}
1073 sendto(Socket, Data, Dest, Flags, Timeout :: nowait) ->
1075 ok |
1076 {ok, {binary(), SelectInfo}} |
1077 {select, SelectInfo} |
1078 {error, Reason}
1079 Types:
1081 Socket = socket()
1083 Data = binary()
1084 Dest = sockaddr()
1085 Flags = send_flags()
1086 SelectInfo = select_info()
1087 Reason = term()
1088 Send a message on a socket, to the specified destination.
1090 In the case when there is no room in the (system-) buffers, the
1092 function will return with the SelectInfo. The caller can then
1093 await a select message, {'$socket', Socket, select, Info} (where
1094 Info is the ref field from the SelectInfo), when there is room
1095 for more data (a subsequent call to sendto will then send the
1096 data).
1097 setopt(Socket, Level :: otp, Key :: otp_socket_option(), Value) ->
1099 ok | {error, Reason}
1100 setopt(Socket, Level :: socket, Key :: socket_option(), Value) ->
1102 ok | {error, Reason}
1103 setopt(Socket, Level :: ip, Key :: ip_socket_option(), Value) ->
1105 ok | {error, Reason}
1106 setopt(Socket, Level :: ipv6, Key :: ipv6_socket_option(), Value) ->
1108 ok | {error, Reason}
1109 setopt(Socket, Level :: tcp, Key :: tcp_socket_option(), Value) ->
1111 ok | {error, Reason}
1112 setopt(Socket, Level :: udp, Key :: udp_socket_option(), Value) ->
1114 ok | {error, Reason}
1115 setopt(Socket, Level :: sctp, Key :: sctp_socket_option(), Value) ->
1117 ok | {error, Reason}
1118 Types:
1120 Socket = socket()
1122 Value = Reason = term()
1123 Set options on a socket.
1125 What properties are valid depend both on Level and on what kind
1127 of socket it is (domain, type and protocol).
1128 See the socket options chapter of the users guide for more info.
1130 Note:
1132 Not all options are valid on all platforms. That is, even if
1133 "we" support an option, that does not mean that the underlying
1134 OS does.
1135 Note:
1138 Sockets are set 'non-blocking' when created, so this option is
1139 *not* available (as it would adversely effect the Erlang VM to
1140 set a socket 'blocking').
1141 setopt(Socket, Level, Key, Value) -> ok | {error, Reason}
1144 Types:
1146 Socket = socket()
1148 Level = Key = integer() >= 0
1149 Value = binary()
1150 Reason = term()
1151 Set options on a socket.
1153 When specifying Level as an integer, and therefor using "native
1155 mode", it is *currently* up to the caller to know how to encode
1156 the Value.
1157 For more info, see setopt above.
1159 shutdown(Socket, How) -> ok | {error, Reason}
1161 Types:
1163 Socket = socket()
1165 How = shutdown_how()
1166 Reason = term()
1167 Shut down all or part of a full-duplex connection.
1169 sockname(Socket) -> {ok, SockAddr} | {error, Reason}
1171 Types:
1173 Socket = socket()
1175 SockAddr = sockaddr()
1176 Reason = term()
1177 Returns the current address to which the socket is bound.
1179 supports() ->
1181 [{options, supports_options()} |
1182 {sctp, boolean()} |
1183 {ipv6, boolean()} |
1184 {local, boolean()} |
1185 {send_flags, supports_send_flags()} |
1186 {recv_flags, supports_recv_flags()}]
1187 supports(Key1 :: options) -> supports_options()
1189 supports(Key1 :: sctp) -> boolean()
1191 supports(Key1 :: ipv6) -> boolean()
1193 supports(Key1 :: local) -> boolean()
1195 supports(Key1 :: send_flags) -> supports_send_flags()
1197 supports(Key1 :: recv_flags) -> supports_recv_flags()
1199 supports(Key1) -> false
1201 supports(Key1 :: options, Level :: socket) ->
1203 supports_options_socket()
1204 supports(Key1 :: options, Level :: ip) -> supports_options_ip()
1206 supports(Key1 :: options, Level :: ipv6) ->
1208 supports_options_ipv6()
1209 supports(Key1 :: options, Level :: tcp) -> supports_options_tcp()
1211 supports(Key1 :: options, Level :: udp) -> supports_options_udp()
1213 supports(Key1 :: options, Level :: sctp) ->
1215 supports_options_sctp()
1216 supports(Key1 :: send_flags, SendFlag :: send_flag()) -> boolean()
1218 supports(Key1 :: recv_flags, RecvFlag :: recv_flag()) -> boolean()
1220 supports(Key1, Key2) -> false
1222 supports(Key1 :: options, Level :: socket, Opt :: socket_option()) ->
1224 boolean()
1225 supports(Key1 :: options, Level :: ip, Opt :: ip_socket_option()) ->
1227 boolean()
1228 supports(Key1 :: options,
1230 Level :: ipv6,
1231 Opt :: ipv6_socket_option()) ->
1232 boolean()
1233 supports(Key1 :: options,
1235 Level :: tcp,
1236 Opt :: tcp_socket_option()) ->
1237 boolean()
1238 supports(Key1 :: options,
1240 Level :: udp,
1241 Opt :: udp_socket_option()) ->
1242 boolean()
1243 supports(Key1 :: options,
1245 Level :: sctp,
1246 Opt :: sctp_socket_option()) ->
1247 boolean()
1248 supports(Key1, Key2, Key3) -> false
1250 Types:
1252 Key1 = Key2 = Key3 = term()
1254 This function intends to retreive information about what the
1256 platform supports. Such as if SCTP is supported. Or which socket
1257 options are supported.
1258 which_sockets() -> [socket()]
1260 which_sockets(FilterRule) -> [socket()]
1262 Types:
1264 FilterRule =
1266 inet | inet6 | stream | dgram | seqpacket | sctp | tcp |
1267 udp |
1268 pid() |
1269 fun((socket_info()) -> boolean())
1270 Returns a list of all sockets, according to the filter rule.
1272 There are several pre-made filter rule(s) and one general:
1274 inet | inet6:
1276 Selection based on the domain of the socket.
1277 Only a subset is valid.
1278 stream | dgram | seqpacket:
1280 Selection based on the type of the socket.
1281 Only a subset is valid.
1282 sctp | tcp | udp:
1284 Selection based on the protocol of the socket.
1285 Only a subset is valid.
1286 pid():
1288 Selection base on which sockets has this pid as Controlling
1289 Process.
1290 fun((socket_info()) -> boolean()):
1292 The general filter rule.
1293 A fun that takes the socket info and returns a boolean()
1294 (true if the socket sould be included and false if should
1295 not).
1296
1298 client(Addr, SAddr, SPort) ->
1299 {ok, Sock} = socket:open(inet, stream, tcp),
1300 {ok, _} = socket:bind(Sock, #{family => inet,
1301 addr => Addr}),
1302 ok = socket:connect(Sock, #{family => inet,
1303 addr => SAddr,
1304 port => SPort}),
1305 Msg = list_to_binary("hello"),
1306 ok = socket:send(Sock, Msg),
1307 ok = socket:shutdown(Sock, write),
1308 {ok, Msg} = socket:recv(Sock),
1309 ok = socket:close(Sock).
1310 server(Addr, Port) ->
1312 {ok, LSock} = socket:open(inet, stream, tcp),
1313 {ok, _} = socket:bind(LSock, #{family => inet,
1314 port => Port,
1315 addr => Addr}),
1316 ok = socket:listen(LSock),
1317 {ok, Sock} = socket:accept(LSock),
1318 {ok, Msg} = socket:recv(Sock),
1319 ok = socket:send(Sock, Msg),
1320 ok = socket:shutdown(Sock, write),
1321 ok = socket:close(Sock),
1322 ok = socket:close(LSock).
1323Ericsson AB erts 10.7.1 socket(3)