1socket(3) Erlang Module Definition socket(3)
2
6 socket - Socket interface.
7
9 This module provides an API for the socket interface. It is used to
10 create, delete and manipulate sockets, send and receive data.
11 The idea is that it shall be as "close as possible" to the OS level
13 socket interface. The only significant addition is that some of the
14 functions, e.g. recv/3, has a timeout argument.
15 Note:
17 Some functions allow for an asynchronous call. This is achieved by
18 setting the Timeout argument to nowait. For instance, if calling the
19 recv/3 function with Timeout set to nowait (recv(Sock, 0, nowait)) when
20 there is actually nothing to read, it will return with {select,
21 SelectInfo} (SelectInfo contains the SelectRef). When data eventually
22 arrives a 'select' message will be sent to the caller:
23 : {'$socket', socket(), select, SelectRef}
25 The caller can now make another call to the recv function and now
27 expect data.
28 Note that all other users are locked out until the 'current user' has
30 called the function (recv in this case).
31 Another message the user must be prepared for (when making asynchronous
33 calls) is the abort message:
34 : {'$socket', socket(), abort, Info}
36 This message indicates that the (asynchronous) operation has been
38 aborted. If, for instance, the socket has been closed (by another
39 process), Info will be {SelectRef, closed}.
40 Note:
43 There is currently no support for Windows.
44 Support for IPv6 has been implemented but not tested.
46 SCTP has only been partly implemented (and not tested).
48
51 domain() = local | inet | inet6
52 type() = stream | dgram | raw | rdm | seqpacket
54 protocol() =
56 ip | tcp | udp | sctp | icmp | igmp | {raw, integer()}
57 socket()
59 As returned by open/2,3,4 and accept/1,2.
61 select_tag()
63 A tag that describes the (select) operation.
65 select_ref()
67 A reference that uniquely identifies the (select) operation.
69 select_info() = {select_info, select_tag(), select_ref()}
71 socket_counters() = [{socket_counter(), integer() >= 0}]
73 socket_counter() =
75 read_byte | read_fails | read_pkg | read_tries | read_waits |
76 write_byte | write_fails | write_pkg | write_tries |
77 write_waits
78 socket_info() =
80 #{counters := socket_counters(),
81 num_readers := integer() >= 0,
82 num_writers := integer() >= 0,
83 num_acceptors := integer() >= 0}
84 ip4_address() = {0..255, 0..255, 0..255, 0..255}
86 ip6_address() =
88 {0..65535,
89 0..65535,
90 0..65535,
91 0..65535,
92 0..65535,
93 0..65535,
94 0..65535,
95 0..65535}
96 ip_address() = ip4_address() | ip6_address()
98 sockaddr() = sockaddr_in4() | sockaddr_in6() | sockaddr_un()
100 sockaddr_in4() =
102 #{family := inet,
103 port := port_number(),
104 addr := any | broadcast | loopback | ip4_address()}
105 sockaddr_in6() =
107 #{family := inet6,
108 port := port_number(),
109 addr := any | loopback | ip6_address(),
110 flowinfo := in6_flow_info(),
111 scope_id := in6_scope_id()}
112 sockaddr_un() = #{family := local, path := binary() | string()}
114 port_number() = 0..65535
116 in6_flow_info() = uint20()
118 in6_scope_id() = uint32()
120 accept_flags() = [accept_flag()]
122 accept_flag() = nonblock | cloexec
124 send_flags() = [send_flag()]
126 send_flag() = confirm | dontroute | eor | more | nosignal | oob
128 recv_flags() = [recv_flag()]
130 recv_flag() = cmsg_cloexec | errqueue | oob | peek | trunc
132 shutdown_how() = read | write | read_write
134 sockopt_level() =
136 otp | socket | ip | ipv6 | tcp | udp | sctp |
137 integer() >= 0
138 otp_socket_option() =
140 debug | iow | controlling_process | rcvbuf | rcvctrlbuf |
141 sndctrlbuf | fd
142 socket_option() =
144 acceptconn | acceptfilter | bindtodevice | broadcast |
145 busy_poll | debug | domain | dontroute | error | keepalive |
146 linger | mark | oobinline | passcred | peek_off | peekcred |
147 priority | protocol | rcvbuf | rcvbufforce | rcvlowat |
148 rcvtimeo | reuseaddr | reuseport | rxq_ovfl | setfib |
149 sndbuf | sndbufforce | sndlowat | sndtimeo | timestamp | type
150 ip_socket_option() =
152 add_membership | add_source_membership | block_source |
153 dontfrag | drop_membership | drop_source_membership |
154 freebind | hdrincl | minttl | msfilter | mtu | mtu_discover |
155 multicast_all | multicast_if | multicast_loop |
156 multicast_ttl | nodefrag | options | pktinfo | recverr |
157 recvif | recvdstaddr | recvopts | recvorigdstaddr | recvtos |
158 recvttl | retopts | router_alert | sndsrcaddr | tos |
159 transparent | ttl | unblock_source
160 ipv6_socket_option() =
162 addrform | add_membership | authhdr | auth_level | checksum |
163 drop_membership | dstopts | esp_trans_level |
164 esp_network_level | faith | flowinfo | hoplimit | hopopts |
165 ipcomp_level | join_group | leave_group | mtu | mtu_discover |
166 multicast_hops | multicast_if | multicast_loop | portrange |
167 pktoptions | recverr | recvpktinfo | pktinfo | recvtclass |
168 router_alert | rthdr | tclass | unicast_hops | use_min_mtu |
169 v6only
170 tcp_socket_option() =
172 congestion | cork | info | keepcnt | keepidle | keepintvl |
173 maxseg | md5sig | nodelay | noopt | nopush | syncnt |
174 user_timeout
175 udp_socket_option() = cork
177 sctp_socket_option() =
179 adaption_layer | associnfo | auth_active_key | auth_asconf |
180 auth_chunk | auth_key | auth_delete_key | autoclose |
181 context | default_send_params | delayed_ack_time |
182 disable_fragments | hmac_ident | events | explicit_eor |
183 fragment_interleave | get_peer_addr_info | initmsg |
184 i_want_mapped_v4_addr | local_auth_chunks | maxseg |
185 maxburst | nodelay | partial_delivery_point |
186 peer_addr_params | peer_auth_chunks | primary_addr |
187 reset_streams | rtoinfo | set_peer_primary_addr | status |
188 use_ext_recvinfo
189 timeval() = #{sec := integer(), usec := integer()}
191 ip_tos() =
193 lowdeley | throughput | reliability | mincost | integer()
194 ip_mreq() =
196 #{multiaddr := ip4_address(),
197 interface := any | ip4_address()}
198 ip_mreq_source() =
200 #{multiaddr := ip4_address(),
201 interface := ip4_address(),
202 sourceaddr := ip4_address()}
203 ip_pmtudisc() = want | dont | do | probe
205 ip_msfilter_mode() = include | exclude
207 ip_msfilter() =
209 #{multiaddr := ip4_address(),
210 interface := ip4_address(),
211 mode := ip_msfilter_mode(),
212 slist := [ip4_address()]}
213 ip_pktinfo() =
215 #{ifindex := integer() >= 0,
216 spec_dst := ip4_address(),
217 addr := ip4_address()}
218 ipv6_mreq() =
220 #{multiaddr := ip6_address(), interface := integer() >= 0}
221 ipv6_pmtudisc() = ip_pmtudisc()
223 ipv6_pktinfo() = #{addr := ip6_address(), ifindex := integer()}
225 sctp_assoc_id() = int32()
227 sctp_sndrcvinfo() =
229 #{stream := uint16(),
230 ssn := uint16(),
231 flags := uint16(),
232 ppid := uint16(),
233 context := uint16(),
234 timetolive := uint16(),
235 tsn := uint16(),
236 cumtsn := uint16(),
237 assoc_id := sctp_assoc_id()}
238 sctp_event_subscribe() =
240 #{data_in := boolean(),
241 association := boolean(),
242 address := boolean(),
243 send_failure := boolean(),
244 peer_error := boolean(),
245 shutdown := boolean(),
246 partial_delivery := boolean(),
247 adaptation_layer := boolean(),
248 authentication := boolean(),
249 sender_dry := boolean()}
250 sctp_assocparams() =
252 #{assoc_id := sctp_assoc_id(),
253 max_rxt := uint16(),
254 num_peer_dests := uint16(),
255 peer_rwnd := uint32(),
256 local_rwnd := uint32(),
257 cookie_life := uint32()}
258 sctp_initmsg() =
260 #{num_outstreams := uint16(),
261 max_instreams := uint16(),
262 max_attempts := uint16(),
263 max_init_timeo := uint16()}
264 sctp_rtoinfo() =
266 #{assoc_id := sctp_assoc_id(),
267 initial := uint32(),
268 max := uint32(),
269 min := uint32()}
270 msghdr_flag() = ctrunc | eor | errqueue | oob | trunc
272 msghdr_flags() = [msghdr_flag()]
274 msghdr() =
276 #{addr := sockaddr(),
277 iov := [binary()],
278 ctrl := [cmsghdr_recv()] | [cmsghdr_send()],
279 flags := msghdr_flags()}
280 cmsghdr_level() = socket | ip | ipv6 | integer()
282 cmsghdr_type() =
284 timestamp | pktinfo | tos | ttl | rights | credentials |
285 origdstaddr |
286 integer()
287 cmsghdr_recv() =
289 #{level := socket, type := timestamp, data := timeval()} |
290 #{level := socket, type := rights, data := binary()} |
291 #{level := socket, type := credentials, data := binary()} |
292 #{level := socket, type := integer(), data := binary()} |
293 #{level := ip, type := tos, data := ip_tos()} |
294 #{level := ip, type := ttl, data := integer()} |
295 #{level := ip, type := pktinfo, data := ip_pktinfo()} |
296 #{level := ip, type := origdstaddr, data := sockaddr_in4()} |
297 #{level := ip, type := integer(), data := binary()} |
298 #{level := ipv6, type := pktinfo, data := ipv6_pktinfo()} |
299 #{level := ipv6, type := integer(), data := binary()} |
300 #{level := integer(), type := integer(), data := binary()}
301 cmsghdr_send() =
303 #{level := socket, type := integer(), data := binary()} |
304 #{level := ip, type := tos, data := ip_tos() | binary()} |
305 #{level := ip, type := ttl, data := integer() | binary()} |
306 #{level := ip, type := integer(), data := binary()} |
307 #{level := ipv6, type := integer(), data := binary()} |
308 #{level := udp, type := integer(), data := binary()} |
309 #{level := integer(), type := integer(), data := binary()}
310 uint8() = 0..255
312 uint16() = 0..65535
314 uint20() = 0..1048575
316 uint32() = 0..4294967295
318 int32() = -2147483648..2147483647
320 supports_options_socket() = [{socket_option(), boolean()}]
322 supports_options_ip() = [{ip_socket_option(), boolean()}]
324 supports_options_ipv6() = [{ipv6_socket_option(), boolean()}]
326 supports_options_tcp() = [{tcp_socket_option(), boolean()}]
328 supports_options_udp() = [{udp_socket_option(), boolean()}]
330 supports_options_sctp() = [{sctp_socket_option(), boolean()}]
332 supports_options() =
334 [{socket, supports_options_socket()} |
335 {ip, supports_options_ip()} |
336 {ipv6, supports_options_ipv6()} |
337 {tcp, supports_options_tcp()} |
338 {udp, supports_options_udp()} |
339 {sctp, supports_options_sctp()}]
340
342 accept(LSocket) -> {ok, Socket} | {error, Reason}
343 accept(LSocket, Timeout) -> {ok, Socket} | {error, Reason}
345 Types:
347 LSocket = socket()
349 Timeout = timeout()
350 Socket = socket()
351 Reason = term()
352 Accept a connection on a socket.
354 This call is used with connection-based socket types (stream or
356 seqpacket). It extracs the first pending connection request for
357 the listen socket and returns the (newly) connected socket.
358 accept(LSocket, Timeout :: nowait) ->
360 {ok, Socket} | {select, SelectInfo} | {error, Reason}
361 Types:
363 LSocket = Socket = socket()
365 SelectInfo = select_info()
366 Reason = term()
367 Accept a connection on a socket.
369 This call is used with connection-based socket types (stream or
371 seqpacket). It extracs the first pending connection request for
372 the listen socket and returns the (newly) connected socket.
373 In the case when there is no connections waiting, the function
375 will return with the SelectInfo. The caller can then await a
376 select message, {'$socket', Socket, select, Info} (where Info is
377 the ref field from the SelectInfo), when a client connects (a
378 subsequent call to accept will then return the socket).
379 bind(Socket, Addr) -> ok | {error, Reason}
381 Types:
383 Socket = socket()
385 Addr = any | broadcast | loopback | sockaddr()
386 Reason = term()
387 Bind a name to a socket.
389 When a socket is created (with open), it has no address assigned
391 to it. bind assigns the address specified by the Addr argument.
392 The rules used for name binding vary between domains.
394 cancel(Socket, SelectInfo) -> ok | {error, Reason}
396 Types:
398 Socket = socket()
400 SelectInfo = select_info()
401 Reason = term()
402 Cancel an asynchronous request.
404 Call this function in order to cancel a previous asynchronous
406 call to, e.g. recv/3.
407 close(Socket) -> ok | {error, Reason}
409 Types:
411 Socket = socket()
413 Reason = term()
414 Closes the socket.
416 Note:
418 Note that for e.g. protocol = tcp, most implementations doing a
419 close does not guarantee that any data sent is delivered to the
420 recipient before the close is detected at the remote side.
421 One way to handle this is to use the shutdown function
423 (socket:shutdown(Socket, write)) to signal that no more data is
424 to be sent and then wait for the read side of the socket to be
425 closed.
426 connect(Socket, SockAddr) -> ok | {error, Reason}
429 connect(Socket, SockAddr, Timeout) -> ok | {error, Reason}
431 Types:
433 Socket = socket()
435 SockAddr = sockaddr()
436 Timeout = timeout()
437 Reason = term()
438 This function connects the socket to the address specied by the
440 SockAddr argument.
441 connect(Socket, SockAddr, Timeout :: nowait) ->
443 ok | {select, SelectInfo} | {error, Reason}
444 Types:
446 Socket = socket()
448 SockAddr = sockaddr()
449 SelectInfo = select_info()
450 Reason = term()
451 This function connects the socket to the address specied by the
453 SockAddr argument.
454 In the case when its not possible to immediately establish a
456 connection, the function will return with the SelectInfo. The
457 caller can then await a select message, {'$socket', Socket,
458 select, Info} (where Info is the ref field from the SelectInfo,
459 a subsequent call to connect will then establish the connec‐
460 tion).
461 getopt(Socket, Level :: otp, Key :: otp_socket_option()) ->
463 {ok, Value} | {error, Reason}
464 getopt(Socket, Level :: socket, Key :: socket_option()) ->
466 {ok, Value} | {error, Reason}
467 getopt(Socket, Level :: ip, Key :: ip_socket_option()) ->
469 {ok, Value} | {error, Reason}
470 getopt(Socket, Level :: ipv6, Key :: ipv6_socket_option()) ->
472 {ok, Value} | {error, Reason}
473 getopt(Socket, Level :: tcp, Key :: tcp_socket_option()) ->
475 {ok, Value} | {error, Reason}
476 getopt(Socket, Level :: udp, Key :: udp_socket_option()) ->
478 {ok, Value} | {error, Reason}
479 getopt(Socket, Level :: sctp, Key :: sctp_socket_option()) ->
481 {ok, Value} | {error, Reason}
482 Types:
484 Socket = socket()
486 Value = Reason = term()
487 Get an option on a socket.
489 What properties are valid depend both on Level and on what kind
491 of socket it is (domain, type and protocol).
492 See the socket options chapter of the users guide for more info.
494 Note:
496 Not all options are valid on all platforms. That is, even if
497 "we" support an option, that does not mean that the underlying
498 OS does.
499 getopt(Socket, Level, Key) -> ok | {ok, Value} | {error, Reason}
502 Types:
504 Socket = socket()
506 Level = integer()
507 Key = {NativeOpt, ValueSize}
508 NativeOpt = integer()
509 ValueSize = int | bool | integer() >= 0
510 Value = Reason = term()
511 Get an option on a socket.
513 What properties are valid depend both on Level and on what kind
515 of socket it is (domain, type and protocol).
516 When specifying Level as an integer, and therefor using "native
518 mode", it is *currently* up to the caller to know how to inter‐
519 pret the result.
520 See the socket options chapter of the users guide for more info.
522 Note:
524 Not all options are valid on all platforms. That is, even if
525 "we" support an option, that does not mean that the underlying
526 OS does.
527 info(Socket) -> socket_info()
530 Types:
532 Socket = socket()
534 Get miscellaneous info about the socket.
536 The function returns a map with each info item as a key-value
538 binding. It reflects the "current" state of the socket.
539 Note:
541 In order to ensure data integrity, mutex'es are taken when
542 needed. So, do not call this function often.
543 listen(Socket) -> ok | {error, Reason}
546 listen(Socket, Backlog) -> ok | {error, Reason}
548 Types:
550 Socket = socket()
552 Backlog = integer() >= 1
553 Reason = term()
554 Listen for connections on a socket.
556 open(Domain, Type) -> {ok, Socket} | {error, Reason}
558 open(Domain, Type, Protocol) -> {ok, Socket} | {error, Reason}
560 open(Domain, Type, Protocol, Extra) ->
562 {ok, Socket} | {error, Reason}
563 Types:
565 Domain = domain()
567 Type = type()
568 Protocol = default | protocol()
569 Extra = map()
570 Socket = socket()
571 Reason = term()
572 Creates an endpoint (socket) for communication.
574 For some types there is a default protocol, indicated by
576 default, which it may be possible to specify. And for Domain =
577 local, if a protocol is pecified, it must be default.
578 The Extra argument is intended for "obscure" options. Currently
580 the only supported option is netns, which is only supported on
581 the linux platform.
582 Note:
584 It may not be possible to specify the default protocol (except
585 when Domain = local). We need to be able to retreive the result‐
586 ing protocol, which is not possble on all platforms.
587 peername(Socket) -> {ok, SockAddr} | {error, Reason}
590 Types:
592 Socket = socket()
594 SockAddr = sockaddr()
595 Reason = term()
596 Returns the address of the peer connected to the socket.
598 recv(Socket) -> {ok, Data} | {error, Reason}
600 recv(Socket, Length) -> {ok, Data} | {error, Reason}
602 recv(Socket, Length, Flags) -> {ok, Data} | {error, Reason}
604 recv(Socket, Length, Timeout) -> {ok, Data} | {error, Reason}
606 recv(Socket, Length, Flags, Timeout) ->
608 {ok, Data} | {error, Reason}
609 Types:
611 Socket = socket()
613 Length = integer() >= 0
614 Flags = recv_flags()
615 Timeout = timeout()
616 Data = binary()
617 Reason = term()
618 Receive a message from a socket.
620 There is a special case for the argument Length. If it is set to
622 zero (0), it means "give me everything you currently have".
623 recv(Socket, Length, Timeout :: nowait) ->
625 {ok, Data} |
626 {select, SelectInfo} |
627 {ok, {Data, SelectInfo}} |
628 {error, Reason}
629 recv(Socket, Length, Flags, Timeout :: nowait) ->
631 {ok, Data} |
632 {select, SelectInfo} |
633 {ok, {Data, SelectInfo}} |
634 {error, Reason}
635 Types:
637 Socket = socket()
639 Length = integer() >= 0
640 Flags = recv_flags()
641 Data = binary()
642 SelectInfo = select_info()
643 Reason = term()
644 Receive a message from a socket.
646 There is a special case for the argument Length. If it is set to
648 zero (0), it means "give me everything you currently have".
649 In the case when there is no data waiting, the function will
651 return with the SelectInfo. The caller can then await a select
652 message, {'$socket', Socket, select, Info} (where Info is the
653 ref field from the SelectInfo), when data has arrived (a subse‐
654 quent call to recv will then return the data).
655 Note that if a length (> 0) is specified, and only part of that
657 amount of data is available, the function will return with that
658 data and the SelectInfo (if the caller don't want to wait for
659 the remaining data, it must immediately call the cancel/2 func‐
660 tion.)
661 recvfrom(Socket) -> {ok, {Source, Data}} | {error, Reason}
663 recvfrom(Socket, BufSz) -> {ok, {Source, Data}} | {error, Reason}
665 recvfrom(Socket, Flags, Timeout) ->
667 {ok, {Source, Data}} | {error, Reason}
668 recvfrom(Socket, BufSz, Flags) ->
670 {ok, {Source, Data}} | {error, Reason}
671 recvfrom(Socket, BufSz, Timeout) ->
673 {ok, {Source, Data}} | {error, Reason}
674 recvfrom(Socket, BufSz, Flags, Timeout) ->
676 {ok, {Source, Data}} | {error, Reason}
677 Types:
679 Socket = socket()
681 BufSz = integer() >= 0
682 Flags = recv_flags()
683 Timeout = timeout()
684 Source = sockaddr() | undefined
685 Data = binary()
686 Reason = term()
687 Receive a message from a socket.
689 This function reads "messages", which means that regardless of
691 how much we want to read, it returns when we get a message (if
692 the buffer size is to small, the message will be truncated).
693 The BufSz argument basically defines the size of the receive
695 buffer. By setting the value to zero (0), the configured size
696 (setopt with Level = otp and Key = rcvbuf) is used.
697 It may be impossible to know what (buffer) size is appropriate
699 "in advance", and in those cases it may be convenient to use the
700 (recv) 'peek' flag. When this flag is provided, the message is
701 *not* "consumed" from the underlying buffers, so another
702 recvfrom call is needed, possibly with a then adjusted buffer
703 size.
704 recvfrom(Socket, Flags, Timeout :: nowait) ->
706 {ok, {Source, Data}} |
707 {select, SelectInfo} |
708 {error, Reason}
709 recvfrom(Socket, BufSz, Timeout :: nowait) ->
711 {ok, {Source, Data}} |
712 {select, SelectInfo} |
713 {error, Reason}
714 recvfrom(Socket, BufSz, Flags, Timeout :: nowait) ->
716 {ok, {Source, Data}} |
717 {select, SelectInfo} |
718 {error, Reason}
719 Types:
721 Socket = socket()
723 BufSz = integer() >= 0
724 Flags = recv_flags()
725 Source = sockaddr() | undefined
726 Data = binary()
727 SelectInfo = select_info()
728 Reason = term()
729 Receive a message from a socket.
731 This function reads "messages", which means that regardless of
733 how much we want to read, it returns when we get a message (if
734 the buffer size is to small, the message will be truncated).
735 The BufSz argument basically defines the size of the receive
737 buffer. By setting the value to zero (0), the configured size
738 (setopt with Level = otp and Key = rcvbuf) is used.
739 It may be impossible to know what (buffer) size is appropriate
741 "in advance", and in those cases it may be convenient to use the
742 (recv) 'peek' flag. When this flag is provided, the message is
743 *not* "consumed" from the underlying buffers, so another
744 recvfrom call is needed, possibly with a then adjusted buffer
745 size.
746 In the case when there is no data waiting, the function will
748 return with the SelectInfo. The caller can then await a select
749 message, {'$socket', Socket, select, Info} (where Info is the
750 ref field from the SelectInfo), when data has arrived (a subse‐
751 quent call to recvfrom will then return the data).
752 recvmsg(Socket) -> {ok, MsgHdr} | {error, Reason}
754 recvmsg(Socket, Flags) -> {ok, MsgHdr} | {error, Reason}
756 recvmsg(Socket, Timeout) -> {ok, MsgHdr} | {error, Reason}
758 recvmsg(Socket, Flags, Timeout) -> {ok, MsgHdr} | {error, Reason}
760 recvmsg(Socket, BufSz, CtrlSz) -> {ok, MsgHdr} | {error, Reason}
762 recvmsg(Socket, BufSz, CtrlSz, Flags, Timeout) ->
764 {ok, MsgHdr} | {error, Reason}
765 Types:
767 Socket = socket()
769 BufSz = CtrlSz = integer() >= 0
770 Flags = recv_flags()
771 Timeout = timeout()
772 MsgHdr = msghdr()
773 Reason = term()
774 Receive a message from a socket.
776 This function reads "messages", which means that regardless of
778 how much we want to read, it returns when we get a message.
779 The message will be delivered in the form of a msghdr(), which
781 may contain the source address (if socket not connected), a list
782 of cmsghdr_recv() (depends on what socket options have been set
783 and what the protocol and platform supports) and also a set of
784 flags, providing further info about the read.
785 The BufSz argument basically defines the size of the receive
787 buffer. By setting the value to zero (0), the configured size
788 (setopt with Level = otp and Key = rcvbuf) is used.
789 The CtrlSz argument basically defines the size of the receive
791 buffer for the control messages. By setting the value to zero
792 (0), the configured size (setopt with Level = otp) is used.
793 It may be impossible to know what (buffer) size is appropriate
795 "in advance", and in those cases it may be convenient to use the
796 (recv) 'peek' flag. When this flag is provided, the message is
797 *not* "consumed" from the underlying buffers, so another recvmsg
798 call is needed, possibly with a then adjusted buffer size.
799 recvmsg(Socket, Timeout :: nowait) ->
801 {ok, MsgHdr} | {select, SelectInfo} | {error, Reason}
802 recvmsg(Socket, Flags, Timeout :: nowait) ->
804 {ok, MsgHdr} | {select, SelectInfo} | {error, Reason}
805 recvmsg(Socket, BufSz, CtrlSz, Flags, Timeout :: nowait) ->
807 {ok, MsgHdr} | {select, SelectInfo} | {error, Reason}
808 Types:
810 Socket = socket()
812 BufSz = CtrlSz = integer() >= 0
813 Flags = recv_flags()
814 MsgHdr = msghdr()
815 SelectInfo = select_info()
816 Reason = term()
817 Receive a message from a socket.
819 This function reads "messages", which means that regardless of
821 how much we want to read, it returns when we get a message.
822 The message will be delivered in the form of a msghdr(), which
824 may contain the source address (if socket not connected), a list
825 of cmsghdr_recv() (depends on what socket options have been set
826 and what the protocol and platform supports) and also a set of
827 flags, providing further info about the read.
828 The BufSz argument basically defines the size of the receive
830 buffer. By setting the value to zero (0), the configured size
831 (setopt with Level = otp and Key = rcvbuf) is used.
832 The CtrlSz argument basically defines the size of the receive
834 buffer for the control messages. By setting the value to zero
835 (0), the configured size (setopt with Level = otp) is used.
836 It may be impossible to know what (buffer) size is appropriate
838 "in advance", and in those cases it may be convenient to use the
839 (recv) 'peek' flag. When this flag is provided, the message is
840 *not* "consumed" from the underlying buffers, so another recvmsg
841 call is needed, possibly with a then adjusted buffer size.
842 In the case when there is no data waiting, the function will
844 return with the SelectInfo. The caller can then await a select
845 message, {'$socket', Socket, select, Info} (where Info is the
846 ref field from the SelectInfo), when data has arrived (a subse‐
847 quent call to recvmsg will then return the data).
848 send(Socket, Data) -> ok | {error, Reason}
850 send(Socket, Data, Flags) -> ok | {error, Reason}
852 send(Socket, Data, Timeout) -> ok | {error, Reason}
854 send(Socket, Data, Flags, Timeout) -> ok | {error, Reason}
856 Types:
858 Socket = socket()
860 Data = iodata()
861 Flags = send_flags()
862 Timeout = timeout()
863 Reason = term()
864 Send a message on a connected socket.
866 send(Socket, Data, Timeout :: nowait) ->
868 ok |
869 {select, SelectInfo} |
870 {ok, {RestData, SelectInfo}} |
871 {error, Reason}
872 send(Socket, Data, Flags, Timeout :: nowait) ->
874 ok |
875 {select, SelectInfo} |
876 {ok, {RestData, SelectInfo}} |
877 {error, Reason}
878 Types:
880 Socket = socket()
882 Data = iodata()
883 Flags = send_flags()
884 RestData = binary()
885 SelectInfo = select_info()
886 Reason = term()
887 Send a message on a connected socket.
889 In the case when there is no room in the (system-) buffers, the
891 function will return with the SelectInfo. The caller can then
892 await a select message, {'$socket', Socket, select, Info} (where
893 Info is the ref field from the SelectInfo), when there is room
894 for more data (a subsequent call to send will then send the
895 data).
896 Note that if not all the data was sent, the function will return
898 with the remaining data and the SelectInfo (if the caller don't
899 want to wait to be able to send the rest, it should immediately
900 call the cancel/2 function.)
901 sendmsg(Socket, MsgHdr) -> ok | {error, Reason}
903 sendmsg(Socket, MsgHdr, Flags) -> ok | {error, Reason}
905 sendmsg(Socket, MsgHdr, Timeout) -> ok | {error, Reason}
907 sendmsg(Socket, MsgHdr, Flags, Timeout) ->
909 ok | {ok, Remaining} | {error, Reason}
910 Types:
912 Socket = socket()
914 MsgHdr = msghdr()
915 Flags = send_flags()
916 Timeout = timeout()
917 Remaining = erlang:iovec()
918 Reason = term()
919 Send a message on a socket. The destination, if needed (socket
921 not connected) is provided in the MsgHdr, which also contains
922 the message to send, The MsgHdr may also contain an list of
923 optional cmsghdr_send() (depends on what the protocol and plat‐
924 form supports).
925 Unlike the send function, this one sends one message. This means
927 that if, for whatever reason, its not possible to send the mes‐
928 sage in one go, the function will instead return with the
929 remaining data ({ok, Remaining}). Thereby leaving it up to the
930 caller to decide what to do (retry with the remaining data of
931 give up).
932 sendmsg(Socket, MsgHdr, Timeout :: nowait) ->
934 ok | {select, SelectInfo} | {error, Reason}
935 sendmsg(Socket, MsgHdr, Flags, Timeout :: nowait) ->
937 ok |
938 {ok, Remaining} |
939 {select, SelectInfo} |
940 {error, Reason}
941 Types:
943 Socket = socket()
945 MsgHdr = msghdr()
946 Flags = send_flags()
947 Remaining = erlang:iovec()
948 SelectInfo = select_info()
949 Reason = term()
950 Send a message on a socket. The destination, if needed (socket
952 not connected) is provided in the MsgHdr, which also contains
953 the message to send, The MsgHdr may also contain an list of
954 optional cmsghdr_send() (depends on what the protocol and plat‐
955 form supports).
956 Unlike the send function, this one sends one message. This means
958 that if, for whatever reason, its not possible to send the mes‐
959 sage in one go, the function will instead return with the
960 remaining data ({ok, Remaining}). Thereby leaving it up to the
961 caller to decide what to do (retry with the remaining data of
962 give up).
963 In the case when there is no room in the (system-) buffers, the
965 function will return with the SelectInfo. The caller can then
966 await a select message, {'$socket', Socket, select, Info} (where
967 Info is the ref field from the SelectInfo), when there is room
968 for more data (a subsequent call to sendmsg will then send the
969 data).
970 sendto(Socket, Data, Dest) -> ok | {error, Reason}
972 sendto(Socket, Data, Dest, Flags) -> ok | {error, Reason}
974 sendto(Socket, Data, Dest, Timeout) -> ok | {error, Reason}
976 sendto(Socket, Data, Dest, Flags, Timeout) -> ok | {error, Reason}
978 Types:
980 Socket = socket()
982 Data = binary()
983 Dest = sockaddr()
984 Flags = send_flags()
985 Timeout = timeout()
986 Reason = term()
987 Send a message on a socket, to the specified destination.
989 sendto(Socket, Data, Dest, Timeout :: nowait) ->
991 ok | {select, SelectInfo} | {error, Reason}
992 sendto(Socket, Data, Dest, Flags, Timeout :: nowait) ->
994 ok | {select, SelectInfo} | {error, Reason}
995 Types:
997 Socket = socket()
999 Data = binary()
1000 Dest = sockaddr()
1001 Flags = send_flags()
1002 SelectInfo = select_info()
1003 Reason = term()
1004 Send a message on a socket, to the specified destination.
1006 In the case when there is no room in the (system-) buffers, the
1008 function will return with the SelectInfo. The caller can then
1009 await a select message, {'$socket', Socket, select, Info} (where
1010 Info is the ref field from the SelectInfo), when there is room
1011 for more data (a subsequent call to sendto will then send the
1012 data).
1013 setopt(Socket, Level :: otp, Key :: otp_socket_option(), Value) ->
1015 ok | {error, Reason}
1016 setopt(Socket, Level :: socket, Key :: socket_option(), Value) ->
1018 ok | {error, Reason}
1019 setopt(Socket, Level :: ip, Key :: ip_socket_option(), Value) ->
1021 ok | {error, Reason}
1022 setopt(Socket, Level :: ipv6, Key :: ipv6_socket_option(), Value) ->
1024 ok | {error, Reason}
1025 setopt(Socket, Level :: tcp, Key :: tcp_socket_option(), Value) ->
1027 ok | {error, Reason}
1028 setopt(Socket, Level :: udp, Key :: udp_socket_option(), Value) ->
1030 ok | {error, Reason}
1031 setopt(Socket, Level :: sctp, Key :: sctp_socket_option(), Value) ->
1033 ok | {error, Reason}
1034 Types:
1036 Socket = socket()
1038 Value = Reason = term()
1039 Set options on a socket.
1041 What properties are valid depend both on Level and on what kind
1043 of socket it is (domain, type and protocol).
1044 See the socket options chapter of the users guide for more info.
1046 Note:
1048 Not all options are valid on all platforms. That is, even if
1049 "we" support an option, that does not mean that the underlying
1050 OS does.
1051 Note:
1054 Sockets are set 'non-blocking' when created, so this option is
1055 *not* available (as it would adversely effect the Erlang VM to
1056 set a socket 'blocking').
1057 setopt(Socket, Level, Key, Value) -> ok | {error, Reason}
1060 Types:
1062 Socket = socket()
1064 Level = Key = integer() >= 0
1065 Value = binary()
1066 Reason = term()
1067 Set options on a socket.
1069 What properties are valid depend both on Level and on what kind
1071 of socket it is (domain, type and protocol).
1072 See the socket options chapter of the users guide for more info.
1074 Note:
1076 Not all options are valid on all platforms. That is, even if
1077 "we" support an option, that does not mean that the underlying
1078 OS does.
1079 Note:
1082 Sockets are set 'non-blocking' when created, so this option is
1083 *not* available (as it would adversely effect the Erlang VM to
1084 set a socket 'blocking').
1085 shutdown(Socket, How) -> ok | {error, Reason}
1088 Types:
1090 Socket = socket()
1092 How = shutdown_how()
1093 Reason = term()
1094 Shut down all or part of a full-duplex connection.
1096 sockname(Socket) -> {ok, SockAddr} | {error, Reason}
1098 Types:
1100 Socket = socket()
1102 SockAddr = sockaddr()
1103 Reason = term()
1104 Returns the current address to which the socket is bound.
1106 supports() ->
1108 [{options, supports_options()} |
1109 {sctp, boolean()} |
1110 {ipv6, boolean()} |
1111 {local, boolean()}]
1112 supports(Key1 :: options) -> supports_options()
1114 supports(Key1 :: sctp) -> boolean()
1116 supports(Key1 :: ipv6) -> boolean()
1118 supports(Key1 :: local) -> boolean()
1120 supports(Key1 :: options, Level :: socket) ->
1122 supports_options_socket()
1123 supports(Key1 :: options, Level :: ip) -> supports_options_ip()
1125 supports(Key1 :: options, Level :: ipv6) ->
1127 supports_options_ipv6()
1128 supports(Key1 :: options, Level :: tcp) -> supports_options_tcp()
1130 supports(Key1 :: options, Level :: udp) -> supports_options_udp()
1132 supports(Key1 :: options, Level :: sctp) ->
1134 supports_options_sctp()
1135 supports(Key1, Key2) -> false
1137 supports(Key1 :: options, Level :: socket, Opt) -> boolean()
1139 supports(Key1 :: options, Level :: ip, Opt) -> boolean()
1141 supports(Key1 :: options, Level :: ipv6, Opt) -> boolean()
1143 supports(Key1 :: options, Level :: tcp, Opt) -> boolean()
1145 supports(Key1 :: options, Level :: udp, Opt) -> boolean()
1147 supports(Key1 :: options, Level :: sctp, Opt) -> boolean()
1149 supports(Key1, Key2, Key3) -> false
1151 Types:
1153 Key1 = Key2 = Key3 = term()
1155 This function intends to retreive information about what the
1157 platform supports. Such as if SCTP is supported. Or which socket
1158 options are supported.
1159
1161 client(Addr, SAddr, SPort) ->
1162 {ok, Sock} = socket:open(inet, stream, tcp),
1163 {ok, _} = socket:bind(Sock, #{family => inet,
1164 addr => Addr}),
1165 ok = socket:connect(Sock, #{family => inet,
1166 addr => SAddr,
1167 port => SPort}),
1168 Msg = list_to_binary("hello"),
1169 ok = socket:send(Sock, Msg),
1170 ok = socket:shutdown(Sock, write),
1171 {ok, Msg} = socket:recv(Sock),
1172 ok = socket:close(Sock).
1173 server(Addr, Port) ->
1175 {ok, LSock} = socket:open(inet, stream, tcp),
1176 {ok, _} = socket:bind(LSock, #{family => inet,
1177 port => Port,
1178 addr => Addr}),
1179 ok = socket:listen(LSock),
1180 {ok, Sock} = socket:accept(LSock),
1181 {ok, Msg} = socket:recv(Sock),
1182 ok = socket:send(Sock, Msg),
1183 ok = socket:shutdown(Sock, write),
1184 ok = socket:close(Sock),
1185 ok = socket:close(LSock).
1186Ericsson AB erts 10.5.6 socket(3)