1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
|
<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE erlref SYSTEM "erlref.dtd">
<erlref>
<header>
<copyright>
<year>1997</year><year>2021</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
</legalnotice>
<title>gen_tcp</title>
<prepared>tony@erix.ericsson.se</prepared>
<docno></docno>
<date>1997-10-24</date>
<rev>A</rev>
</header>
<module since="">gen_tcp</module>
<modulesummary>Interface to TCP/IP sockets.</modulesummary>
<description>
<p>This module provides functions for communicating
with sockets using the TCP/IP protocol.</p>
<p>The following code fragment is a simple example of
a client connecting to a server at port 5678, transferring a
binary, and closing the connection:</p>
<code type="none">
client() ->
SomeHostInNet = "localhost", % to make it runnable on one machine
{ok, Sock} = gen_tcp:connect(SomeHostInNet, 5678,
[binary, {packet, 0}]),
ok = gen_tcp:send(Sock, "Some Data"),
ok = gen_tcp:close(Sock).</code>
<p>At the other end, a server is listening on port 5678, accepts
the connection, and receives the binary:</p>
<code type="none">
server() ->
{ok, LSock} = gen_tcp:listen(5678, [binary, {packet, 0},
{active, false}]),
{ok, Sock} = gen_tcp:accept(LSock),
{ok, Bin} = do_recv(Sock, []),
ok = gen_tcp:close(Sock),
ok = gen_tcp:close(LSock),
Bin.
do_recv(Sock, Bs) ->
case gen_tcp:recv(Sock, 0) of
{ok, B} ->
do_recv(Sock, [Bs, B]);
{error, closed} ->
{ok, list_to_binary(Bs)}
end.</code>
<p>For more examples, see section
<seeerl marker="#examples">Examples</seeerl>.</p>
<note>
<p>
Functions that create sockets can take an optional option;
<c>{inet_backend, Backend}</c> that, if specified,
has to be the first option. This selects
the implementation backend towards the platform's socket API.
</p>
<p>
This is a <em>temporary</em> option
that will be ignored in a future release.
</p>
<p>
The default is <c>Backend = inet</c>
that selects the traditional <c>inet_drv.c</c> driver.
The other choice is <c>Backend = socket</c>
that selects the new <seeerl marker="socket"><c>socket</c></seeerl>
module and its NIF implementation.
</p>
<p>
The system default can be changed when the node is started
with the application <c>kernel</c>'s configuration variable
<c>inet_backend</c>.
</p>
<p>For <c>gen_tcp</c> with <c>inet_backend = socket</c> we have tried
to be as "compatible" as possible which has sometimes been impossible.
Here is a list of cases when the behaviour of inet-backend
<c>inet</c> (default) and <c>socket</c> are different: </p>
<list type="bulleted">
<item>
<p><seeerl marker="#non_blocking_send">Non-blocking send</seeerl></p>
<p>If a user calling
<seemfa marker="#send/2"><c>gen_tcp:send/2</c></seemfa>
with <c>inet_backend = inet</c>,
tries to send more data than there is room for in the OS buffers,
the "rest data" is buffered by the inet driver (and later sent in the
background).
The effect for the user is that the call is non-blocking.</p>
<p>This is <em>not</em> the effect when
<c>inet_backend = socket</c>, since there is no buffering.
Instead the user hangs either until all data has been sent or the
<c>send_timeout</c> timeout has been reached. </p>
</item>
<item><p>Remote close detected by background send. </p>
<p>An background send will detect a 'remote close' and
(the inet driver will) mark the socket as 'closed'.
No other action is taken.
If the socket has <c>active</c> set to <c>false</c> (passive) at
this point and no one is reading, this will not be noticed.
But as soon as the socket is "activated" (<c>active</c> set to
not <c>false</c>,
<seemfa marker="#send/2">send/2</seemfa>
is called or
<seemfa marker="#recv/2">recv/2,3</seemfa>
is called),
an error message will be sent to the
caller or (socket) owner: <c>{tcp_error, Socket, econnreset}</c>.
Any data in the OS receive buffers will be lost! </p>
<p>This behaviour is <em>not</em> replicated by the socket
implementation.
A send operation will detect a remote close and immediately
return this to the caller, but do nothing else.
A reader will therefor be able to extract any data from the OS buffers.
If the socket is set to <c>active</c> to not <c>false</c>, the data
will be received as expected (<c>{tcp, ...}</c> and then a closed
message (<c>{tcp_closed, ...}</c> will be received (not an error). </p>
</item>
<item>
<p>The option
<seeerl marker="inet#option-show_econnreset">show_econnreset</seeerl>
basically do <em>not</em>
work as described when used with <c>inet_backend = socket</c>.
The "issue" is that a remote close (as described above)
<em>do</em> allow a reader to extract what is in the read buffers
before a close is "delivered".</p>
</item>
<item>
<p>The option
<seeerl marker="inet#option-nodelay">nodelay</seeerl>
is a TCP specific option that is <em>not</em> compatible with
<c>domain = local</c>. </p>
<p>When using <c>inet_backend = socket</c>, trying to create a socket
(via listen or connect) with <c>domain = local</c>
(for example with option {ifaddr, {local,"/tmp/test"}})
<em>will fail</em> with <c>{error, enotsup}</c>. </p>
<p>This does not actually work for <c>inet_backend = inet</c> either,
but in that case the error is simply <em>ignored</em>,
which is a <em>bad</em> idea. We have choosen to <em>not</em>
ignore this error for <c>inet_backend = socket</c>. </p>
</item>
<item>
<p><seeerl marker="#async_shutdown_write">Async shutdown write</seeerl></p>
<p>Calling
<seemfa marker="#shutdown/2">gen_tcp:shutdown(Socket, write | read_write)</seemfa>
on a socket created with <c>inet_backend = socket</c>
will take <em>immediate</em> effect,
unlike for a socket created with <c>inet_backend = inet</c>.</p>
<p>See <seeerl marker="#async_shutdown_write">async shutdown write</seeerl>
for more info. </p>
</item>
</list>
</note>
</description>
<datatypes>
<datatype>
<name name="option"/>
</datatype>
<datatype>
<name name="pktoptions_value"/>
<desc>
<p>
If the platform implements the IPv4 option
<c>IP_PKTOPTIONS</c>, or the IPv6 option
<c>IPV6_PKTOPTIONS</c> or <c>IPV6_2292PKTOPTIONS</c> for the socket
this value is returned from
<seemfa marker="inet#getopts/2"><c>inet:getopts/2</c></seemfa>
when called with the option name
<seetype marker="#option_name"><c>pktoptions</c></seetype>.
</p>
<note>
<p>
This option appears to be VERY Linux specific,
and its existence in future Linux kernel versions
is also worrying since the option is part of RFC 2292
which is since long (2003) obsoleted by RFC 3542
that <em>explicitly</em> removes this possibility to get
packet information from a stream socket.
For comparision: it has existed in FreeBSD but is now removed,
at least since FreeBSD 10.
</p>
</note>
</desc>
</datatype>
<datatype>
<name name="option_name"/>
</datatype>
<datatype>
<name name="connect_option"/>
</datatype>
<datatype>
<name name="listen_option"/>
</datatype>
<datatype>
<name>socket()</name>
<desc><p>As returned by
<seemfa marker="#accept/1"><c>accept/1,2</c></seemfa> and
<seemfa marker="#connect/3"><c>connect/3,4</c></seemfa>.</p>
<marker id="connect"></marker>
</desc>
</datatype>
</datatypes>
<funcs>
<func>
<name name="accept" arity="1" since=""/>
<name name="accept" arity="2" since=""/>
<fsummary>Accept an incoming connection request on a listening socket.</fsummary>
<type_desc variable="ListenSocket">Returned by
<seemfa marker="#listen/2"><c>listen/2</c></seemfa>.
</type_desc>
<desc>
<p>Accepts an incoming connection request on a listening socket.
<c><anno>Socket</anno></c> must be a socket returned from
<seemfa marker="#listen/2"><c>listen/2</c></seemfa>.
<c><anno>Timeout</anno></c> specifies a time-out value in
milliseconds. Defaults to <c>infinity</c>.</p>
<p>Returns:</p>
<list type="bulleted">
<item><p><c>{ok, <anno>Socket</anno>}</c> if a connection is
established</p></item>
<item><p><c>{error, closed}</c> if <c><anno>ListenSocket</anno></c>
is closed</p></item>
<item><p><c>{error, timeout}</c> if no connection is established
within the specified time</p></item>
<item><p><c>{error, system_limit}</c> if all available ports in the
Erlang emulator are in use</p></item>
<item><p>A POSIX error value if something else goes wrong, see
<seeerl marker="inet"><c>inet(3)</c></seeerl> for possible
error values</p></item>
</list>
<p>Packets can be sent to the returned socket <c><anno>Socket</anno></c>
using
<seemfa marker="#send/2"><c>send/2</c></seemfa>.
Packets sent from the peer are delivered as messages (unless
<c>{active, false}</c> is specified in the option list for the
listening socket, in which case packets are retrieved by calling
<seemfa marker="#recv/2"><c>recv/2</c></seemfa>):</p>
<code type="none">
{tcp, Socket, Data}</code>
<note>
<p>The <c>accept</c> call does
<em>not</em> have to be issued from the socket owner
process. Using version 5.5.3 and higher of the emulator,
multiple simultaneous accept calls can be issued from
different processes, which allows for a pool of acceptor
processes handling incoming connections.</p>
</note>
</desc>
</func>
<func>
<name name="close" arity="1" since=""/>
<fsummary>Close a TCP socket.</fsummary>
<desc>
<p>Closes a TCP socket.</p>
<p>Note that in most implementations of TCP, doing a <c>close</c> does
not guarantee that any data sent is delivered to the recipient before
the close is detected at the remote side. If you want to guarantee
delivery of the data to the recipient there are two common ways to
achieve this.</p>
<list type="ordered">
<item><p>Use <seemfa marker="#shutdown/2">
<c>gen_tcp:shutdown(Sock, write)</c></seemfa> to signal that
no more data is to be sent and wait for the read side of the
socket to be closed.</p>
</item>
<item><p>Use the socket option <seeerl marker="inet#packet">
<c>{packet, N}</c></seeerl> (or something similar) to make
it possible for the receiver to close the connection when it
knowns it has received all the data.</p>
</item>
</list>
</desc>
</func>
<func>
<name name="connect" arity="2" clause_i="1" since="OTP 24.3" anchor="connect-sockaddr2"/>
<name name="connect" arity="3" clause_i="2" since="OTP 24.3" anchor="connect-sockaddr3"/>
<fsummary>Connect to a TCP port.</fsummary>
<desc>
<p>Connects to a server according to <c><anno>SockAddr</anno></c>.
This is primarily intended for link local IPv6 addresses
(which require the scope-id),
<seetype marker="socket#sockaddr_in6"><c>socket:sockaddr_in6()</c></seetype>.
But for completeness, we also support IPv4,
<seetype marker="socket#sockaddr_in"><c>socket:sockaddr_in()</c></seetype>.
</p>
<p>The
<seeerl marker="#connect-options"><c>options</c></seeerl>
available are the same as for
<seeerl marker="#connect-port3"><c>connect/3,4</c></seeerl>.</p>
<note>
<p>Keep in mind that if the underlying OS <c>connect()</c> call returns
a timeout, <c>gen_tcp:connect</c> will also return a timeout
(i.e. <c>{error, etimedout}</c>), even if a larger <c>Timeout</c> was
specified.</p>
</note>
<note>
<p>The default values for options specified to <c>connect</c> can
be affected by the Kernel configuration parameter
<c>inet_default_connect_options</c>. For details, see
<seeerl marker="inet"><c>inet(3)</c></seeerl>.</p>
</note>
</desc>
</func>
<func>
<name name="connect" arity="3" clause_i="1" since="" anchor="connect-port3"/>
<name name="connect" arity="4" clause_i="1" since="" anchor="connect-port4"/>
<fsummary>Connect to a TCP port.</fsummary>
<desc>
<p>Connects to a server on TCP port <c><anno>Port</anno></c> on the host
with IP address <c><anno>Address</anno></c>. Argument
<c><anno>Address</anno></c> can be a hostname or an IP address.</p>
<marker id="connect-options"></marker>
<p>The following options are available:</p>
<taglist>
<tag><c>{ip, Address}</c></tag>
<item><p>If the host has many network interfaces, this option
specifies which one to use.</p></item>
<tag><c>{ifaddr, Address}</c></tag>
<item>
<p>Same as <c>{ip, Address}</c>. If the host has many
network interfaces, this option specifies which one to use.</p>
<p>However, if this instead is an
<seetype marker="socket#sockaddr_in">
<c>socket:sockaddr_in()</c></seetype>
or
<seetype marker="socket#sockaddr_in6">
<c>socket:sockaddr_in6()</c></seetype>
this takes precedence over any value previously set with the
<c>ip</c> and <c>port</c> options.
If these options (<c>ip</c> or/and <c>port</c>) however comes
<em>after</em> this option, they may be used to <em>update</em>
their corresponding fields of this options (for <c>ip</c>,
the <c>addr</c> field, and for <c>port</c>, the <c>port</c> field). </p>
</item>
<tag><c>{fd, integer() >= 0}</c></tag>
<item><p>If a socket has somehow been connected without using
<c>gen_tcp</c>, use this option to pass the file descriptor
for it. If <c>{ip, Address}</c> and/or
<c>{port, port_number()}</c> is combined with this option, the
<c>fd</c> is bound to the specified interface and port before
connecting. If these options are not specified, it is assumed that
the <c>fd</c> is already bound appropriately.</p></item>
<tag><c>inet</c></tag>
<item><p>Sets up the socket for IPv4.</p></item>
<tag><c>inet6</c></tag>
<item><p>Sets up the socket for IPv6.</p></item>
<tag><c>local</c></tag>
<item>
<p>
Sets up a Unix Domain Socket. See
<seetype marker="inet#local_address">
<c>inet:local_address()</c>
</seetype>
</p>
</item>
<tag><c>{port, Port}</c></tag>
<item><p>Specifies which local port number to use.</p></item>
<tag><c>{tcp_module, module()}</c></tag>
<item><p>Overrides which callback module is used. Defaults to
<c>inet_tcp</c> for IPv4 and <c>inet6_tcp</c> for IPv6.</p></item>
<tag><c>Opt</c></tag>
<item><p>See
<seemfa marker="inet#setopts/2"><c>inet:setopts/2</c></seemfa>.</p>
</item>
</taglist>
<p>Packets can be sent to the returned socket <c><anno>Socket</anno></c>
using <seemfa marker="#send/2"><c>send/2</c></seemfa>.
Packets sent from the peer are delivered as messages:</p>
<code type="none">
{tcp, Socket, Data}</code>
<p>If the socket is in <c>{active, N}</c> mode (see
<seemfa marker="inet#setopts/2"><c>inet:setopts/2</c></seemfa>
for details) and its message counter drops to <c>0</c>, the following
message is delivered to indicate that the
socket has transitioned to passive (<c>{active, false}</c>) mode:</p>
<code type="none">
{tcp_passive, Socket}</code>
<p>If the socket is closed, the following message is delivered:</p>
<code type="none">
{tcp_closed, Socket}</code>
<p>If an error occurs on the socket, the following message is delivered
(unless <c>{active, false}</c> is specified in the option list for
the socket, in which case packets are retrieved by calling
<seemfa marker="#recv/2"><c>recv/2</c></seemfa>):</p>
<code type="none">
{tcp_error, Socket, Reason}</code>
<p>The optional <c><anno>Timeout</anno></c> parameter specifies a
time-out in milliseconds. Defaults to <c>infinity</c>.</p>
<note>
<p>Keep in mind that if the underlying OS <c>connect()</c> call returns
a timeout, <c>gen_tcp:connect</c> will also return a timeout
(i.e. <c>{error, etimedout}</c>), even if a larger <c>Timeout</c> was
specified.</p>
</note>
<note>
<p>The default values for options specified to <c>connect</c> can
be affected by the Kernel configuration parameter
<c>inet_default_connect_options</c>. For details, see
<seeerl marker="inet"><c>inet(3)</c></seeerl>.</p>
</note>
</desc>
</func>
<func>
<name name="controlling_process" arity="2" since=""/>
<fsummary>Change controlling process of a socket.</fsummary>
<desc>
<p>Assigns a new controlling process <c><anno>Pid</anno></c> to
<c><anno>Socket</anno></c>. The controlling process is the process
that receives messages from the socket. If called by any other
process than the current controlling process,
<c>{error, not_owner}</c> is returned. If the process identified
by <c><anno>Pid</anno></c> is not an existing local pid,
<c>{error, badarg}</c> is returned. <c>{error, badarg}</c> may also
be returned in some cases when <c><anno>Socket</anno></c> is closed
during the execution of this function.</p>
<p>If the socket is set in active mode, this function
will transfer any messages in the mailbox of the caller
to the new controlling process.
If any other process is interacting with the socket while
the transfer is happening, the transfer may not work correctly
and messages may remain in the caller's mailbox. For instance
changing the sockets active mode before the transfer is complete
may cause this.</p>
</desc>
</func>
<func>
<name name="listen" arity="2" since=""/>
<fsummary>Set up a socket to listen on a port.</fsummary>
<desc>
<p>Sets up a socket to listen on port <c><anno>Port</anno></c> on
the local host.</p>
<p>If <c><anno>Port</anno> == 0</c>, the underlying OS assigns an
available port number, use
<seemfa marker="inet#port/1"><c>inet:port/1</c></seemfa>
to retrieve it.</p>
<p>The following options are available:</p>
<taglist>
<tag><c>list</c></tag>
<item><p>Received <c>Packet</c> is delivered as a list.</p></item>
<tag><c>binary</c></tag>
<item><p>Received <c>Packet</c> is delivered as a binary.</p></item>
<tag><c>{backlog, B}</c></tag>
<item><p><c>B</c> is an integer >= <c>0</c>. The backlog value
defines the maximum length that the queue of pending connections
can grow to. Defaults to <c>5</c>.</p></item>
<tag><c>inet6</c></tag>
<item><p>Sets up the socket for IPv6.</p></item>
<tag><c>inet</c></tag>
<item><p>Sets up the socket for IPv4.</p></item>
<tag><c>{fd, Fd}</c></tag>
<item><p>If a socket has somehow been connected without using
<c>gen_tcp</c>, use this option to pass the file
descriptor for it.</p></item>
<tag><c>{ip, Address}</c></tag>
<item>
<p>If the host has many network interfaces, this option
specifies which one to listen on.</p>
</item>
<tag><c>{port, Port}</c></tag>
<item><p>Specifies which local port number to use.</p></item>
<tag><c>{ifaddr, Address}</c></tag>
<item><p>Same as <c>{ip, Address}</c>. If the host has many
network interfaces, this option specifies which one to use.</p>
<p>However, if this instead is an
<seetype marker="socket#sockaddr_in">
<c>socket:sockaddr_in()</c></seetype>
or
<seetype marker="socket#sockaddr_in6">
<c>socket:sockaddr_in6()</c></seetype>
this takes precedence over any value previously set with the
<c>ip</c> and <c>port</c> options.
If these options (<c>ip</c> or/and <c>port</c>) however comes
<em>after</em> this option, they may be used to <em>update</em>
their corresponding fields of this options (for <c>ip</c>,
the <c>addr</c> field, and for <c>port</c>, the <c>port</c> field). </p>
</item>
<tag><c>{tcp_module, module()}</c></tag>
<item><p>Overrides which callback module is used. Defaults to
<c>inet_tcp</c> for IPv4 and <c>inet6_tcp</c> for IPv6.</p></item>
<tag><c>Opt</c></tag>
<item>
<p>See
<seemfa marker="inet#setopts/2"><c>inet:setopts/2</c></seemfa>.
</p>
</item>
</taglist>
<p>The returned socket <c><anno>ListenSocket</anno></c> should be used
in calls to <seemfa marker="#accept/1"><c>accept/1,2</c></seemfa> to
accept incoming connection requests.</p>
<note>
<p>The default values for options specified to <c>listen</c> can
be affected by the Kernel configuration parameter
<c>inet_default_listen_options</c>. For details, see
<seeerl marker="inet"><c>inet(3)</c></seeerl>.</p>
</note>
</desc>
</func>
<func>
<name name="recv" arity="2" since=""/>
<name name="recv" arity="3" since=""/>
<fsummary>Receive a packet from a passive socket.</fsummary>
<type_desc variable="HttpPacket">See the description of
<c>HttpPacket</c> in
<seemfa marker="erts:erlang#decode_packet/3"><c>erlang:decode_packet/3</c></seemfa>
in ERTS.
</type_desc>
<desc>
<p>Receives a packet from a socket in passive
mode. A closed socket is indicated by return value
<c>{error, closed}</c>.</p>
<p>Argument <c><anno>Length</anno></c> is only meaningful when
the socket is in <c>raw</c> mode and denotes the number of
bytes to read. If <c><anno>Length</anno></c> is <c>0</c>, all
available bytes are returned.
If <c><anno>Length</anno></c> > <c>0</c>, exactly
<c><anno>Length</anno></c> bytes are returned, or an error;
possibly discarding less than <c><anno>Length</anno></c> bytes of
data when the socket is closed from the other side.</p>
<p>The optional <c><anno>Timeout</anno></c> parameter specifies a
time-out in milliseconds. Defaults to <c>infinity</c>.</p>
</desc>
</func>
<func>
<name name="send" arity="2" since=""/>
<fsummary>Send a packet.</fsummary>
<desc>
<p>Sends a packet on a socket.</p>
<p>There is no <c>send</c> call with a time-out option, use socket
option <c>send_timeout</c> if time-outs are desired. See section
<seeerl marker="#examples">Examples</seeerl>.</p>
<p>The return value <c>{error, {timeout, RestData}}</c> can
only be returned when <c>inet_backend = socket</c>. </p>
<marker id="non_blocking_send"></marker>
<note>
<p>Non-blocking send.</p>
<p>If the user tries to send more data than there is room for
in the OS send buffers, the 'rest data' is put into (inet driver)
internal buffers and later sent in the background.
The function immediately returns ok (<em>not</em> informing the
caller that not all of the data was actually sent).
Any issue while sending the 'rest data' is maybe returned later. </p>
<p>When using <c>inet_backend = socket</c>, the
behaviour is different. There is <em>no</em>
buffering done (like the inet-driver does), instead
the caller will "hang" until all of the data has been sent or
send timeout (as specified by the <c>send_timeout</c> option)
expires (the function can hang even when using 'inet' backend
if the internal buffers are full). </p>
<p>If this happens when using <c>packet =/= raw</c>, we have a partial
package written. A new package therefor <em>must not</em> be written
at this point, as there is no way for the peer to distinguish this
from the data portion of the current package. Instead, set package
to raw, send the rest data (as raw data) and then set package to
the wanted package type again. </p>
</note>
</desc>
</func>
<func>
<name name="shutdown" arity="2" since=""/>
<fsummary>Asynchronously close a socket.</fsummary>
<desc>
<p>Closes a socket in one or two directions.</p>
<p><c><anno>How</anno> == write</c> means closing the socket for
writing, reading from it is still possible.</p>
<p>If <c><anno>How</anno> == read</c> or there is no outgoing
data buffered in the <c><anno>Socket</anno></c> port,
the socket is shut down immediately and any error encountered
is returned in <c><anno>Reason</anno></c>.</p>
<p>If there is data buffered in the socket port, the attempt
to shutdown the socket is postponed until that data is written to the
kernel socket send buffer. If any errors are encountered, the socket
is closed and <c>{error, closed}</c> is returned on the next
<seemfa marker="#recv/2"><c>recv/2</c></seemfa> or
<seemfa marker="#send/2"><c>send/2</c></seemfa>.</p>
<p>Option <c>{exit_on_close, false}</c> is useful if the peer has done
a shutdown on the write side.</p>
<marker id="async_shutdown_write"></marker>
<note>
<p>Async shutdown write (write or read_write).</p>
<p>If the shutdown attempt is made while the inet-driver
is sending buffered data in the background,
the shutdown is postponed until all buffered data has been sent.
The function immediately returns <c>ok</c> and the caller is
<em>not</em> informed (that the shutdown has <em>not yet</em>
been performed). </p>
<p>When using <c>inet_backend = socket</c>, the
behaviour is different. A shutdown with
<c>How == write | read_write</c>, the operation will
take <em>immediate</em> effect (unlike the inet-driver,
which basically saves the operation for later). </p>
</note>
</desc>
</func>
</funcs>
<section>
<title>Examples</title>
<marker id="examples"></marker>
<p>The following example illustrates use of option
<c>{active,once}</c> and multiple accepts by implementing a server
as a number of worker processes doing accept on a single listening
socket. Function <c>start/2</c> takes the number of worker
processes and the port number on which to listen for incoming
connections. If <c>LPort</c> is specified as <c>0</c>, an
ephemeral port number is used, which is why the start function
returns the actual port number allocated:</p>
<code type="none">
start(Num,LPort) ->
case gen_tcp:listen(LPort,[{active, false},{packet,2}]) of
{ok, ListenSock} ->
start_servers(Num,ListenSock),
{ok, Port} = inet:port(ListenSock),
Port;
{error,Reason} ->
{error,Reason}
end.
start_servers(0,_) ->
ok;
start_servers(Num,LS) ->
spawn(?MODULE,server,[LS]),
start_servers(Num-1,LS).
server(LS) ->
case gen_tcp:accept(LS) of
{ok,S} ->
loop(S),
server(LS);
Other ->
io:format("accept returned ~w - goodbye!~n",[Other]),
ok
end.
loop(S) ->
inet:setopts(S,[{active,once}]),
receive
{tcp,S,Data} ->
Answer = process(Data), % Not implemented in this example
gen_tcp:send(S,Answer),
loop(S);
{tcp_closed,S} ->
io:format("Socket ~w closed [~w]~n",[S,self()]),
ok
end.</code>
<p>Example of a simple client:</p>
<code type="none">
client(PortNo,Message) ->
{ok,Sock} = gen_tcp:connect("localhost",PortNo,[{active,false},
{packet,2}]),
gen_tcp:send(Sock,Message),
A = gen_tcp:recv(Sock,0),
gen_tcp:close(Sock),
A.</code>
<p>The <c>send</c> call does not accept a time-out
option because time-outs on send is handled through socket
option <c>send_timeout</c>. The behavior of a send operation with
no receiver is mainly defined by the underlying TCP
stack and the network infrastructure. To write
code that handles a hanging receiver that can eventually cause
the sender to hang on a <c>send</c> do like the following.</p>
<p>Consider a process that receives data from a client process
to be forwarded to a server on the network. The process is
connected to the server through TCP/IP and does not get any acknowledge
for each message it sends, but has to rely on the send time-out
option to detect that the other end is unresponsive. Option
<c>send_timeout</c> can be used when connecting:</p>
<code type="none">
...
{ok,Sock} = gen_tcp:connect(HostAddress, Port,
[{active,false},
{send_timeout, 5000},
{packet,2}]),
loop(Sock), % See below
...</code>
<p>In the loop where requests are handled, send time-outs can now be
detected:</p>
<code type="none">
loop(Sock) ->
receive
{Client, send_data, Binary} ->
case gen_tcp:send(Sock,[Binary]) of
{error, timeout} ->
io:format("Send timeout, closing!~n",
[]),
handle_send_timeout(), % Not implemented here
Client ! {self(),{error_sending, timeout}},
%% Usually, it's a good idea to give up in case of a
%% send timeout, as you never know how much actually
%% reached the server, maybe only a packet header?!
gen_tcp:close(Sock);
{error, OtherSendError} ->
io:format("Some other error on socket (~p), closing",
[OtherSendError]),
Client ! {self(),{error_sending, OtherSendError}},
gen_tcp:close(Sock);
ok ->
Client ! {self(), data_sent},
loop(Sock)
end
end.</code>
<p>Usually it suffices to detect time-outs on receive, as most
protocols include some sort of acknowledgment from the server,
but if the protocol is strictly one way, option <c>send_timeout</c>
comes in handy.</p>
</section>
</erlref>
|