docs: rename documentation folder to docs
[project/luci.git] / docs / api / modules / nixio.Socket.html
1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
2 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
3 <html>
4 <head>
5 <title>Reference</title>
6 <link rel="stylesheet" href="../luadoc.css" type="text/css" />
7 <!--meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/-->
8 </head>
9
10 <body>
11 <div id="container">
12
13 <div id="product">
14 <div id="product_logo"></div>
15 <div id="product_name"><big><b></b></big></div>
16 <div id="product_description"></div>
17 </div> <!-- id="product" -->
18
19 <div id="main">
20
21 <div id="navigation">
22
23
24 <h1>LuaDoc</h1>
25 <ul>
26
27 <li><a href="../index.html">Index</a></li>
28
29 </ul>
30
31
32 <!-- Module list -->
33
34 <h1>Modules</h1>
35 <ul>
36
37 <li>
38 <a href="../modules/luci.dispatcher.html">luci.dispatcher</a>
39 </li>
40
41 <li>
42 <a href="../modules/luci.http.html">luci.http</a>
43 </li>
44
45 <li>
46 <a href="../modules/luci.http.conditionals.html">luci.http.conditionals</a>
47 </li>
48
49 <li>
50 <a href="../modules/luci.http.date.html">luci.http.date</a>
51 </li>
52
53 <li>
54 <a href="../modules/luci.http.mime.html">luci.http.mime</a>
55 </li>
56
57 <li>
58 <a href="../modules/luci.i18n.html">luci.i18n</a>
59 </li>
60
61 <li>
62 <a href="../modules/luci.ip.html">luci.ip</a>
63 </li>
64
65 <li>
66 <a href="../modules/luci.ip.cidr.html">luci.ip.cidr</a>
67 </li>
68
69 <li>
70 <a href="../modules/luci.json.html">luci.json</a>
71 </li>
72
73 <li>
74 <a href="../modules/luci.jsonc.html">luci.jsonc</a>
75 </li>
76
77 <li>
78 <a href="../modules/luci.jsonc.parser.html">luci.jsonc.parser</a>
79 </li>
80
81 <li>
82 <a href="../modules/luci.model.ipkg.html">luci.model.ipkg</a>
83 </li>
84
85 <li>
86 <a href="../modules/luci.model.uci.html">luci.model.uci</a>
87 </li>
88
89 <li>
90 <a href="../modules/luci.rpcc.html">luci.rpcc</a>
91 </li>
92
93 <li>
94 <a href="../modules/luci.rpcc.ruci.html">luci.rpcc.ruci</a>
95 </li>
96
97 <li>
98 <a href="../modules/luci.sys.html">luci.sys</a>
99 </li>
100
101 <li>
102 <a href="../modules/luci.sys.init.html">luci.sys.init</a>
103 </li>
104
105 <li>
106 <a href="../modules/luci.sys.iptparser.html">luci.sys.iptparser</a>
107 </li>
108
109 <li>
110 <a href="../modules/luci.sys.net.html">luci.sys.net</a>
111 </li>
112
113 <li>
114 <a href="../modules/luci.sys.process.html">luci.sys.process</a>
115 </li>
116
117 <li>
118 <a href="../modules/luci.sys.user.html">luci.sys.user</a>
119 </li>
120
121 <li>
122 <a href="../modules/luci.sys.wifi.html">luci.sys.wifi</a>
123 </li>
124
125 <li>
126 <a href="../modules/luci.util.html">luci.util</a>
127 </li>
128
129 <li>
130 <a href="../modules/nixio.html">nixio</a>
131 </li>
132
133 <li>
134 <a href="../modules/nixio.CHANGELOG.html">nixio.CHANGELOG</a>
135 </li>
136
137 <li>
138 <a href="../modules/nixio.CryptoHash.html">nixio.CryptoHash</a>
139 </li>
140
141 <li>
142 <a href="../modules/nixio.File.html">nixio.File</a>
143 </li>
144
145 <li>
146 <a href="../modules/nixio.README.html">nixio.README</a>
147 </li>
148
149 <li><strong>nixio.Socket</strong></li>
150
151 <li>
152 <a href="../modules/nixio.TLSContext.html">nixio.TLSContext</a>
153 </li>
154
155 <li>
156 <a href="../modules/nixio.TLSSocket.html">nixio.TLSSocket</a>
157 </li>
158
159 <li>
160 <a href="../modules/nixio.UnifiedIO.html">nixio.UnifiedIO</a>
161 </li>
162
163 <li>
164 <a href="../modules/nixio.bin.html">nixio.bin</a>
165 </li>
166
167 <li>
168 <a href="../modules/nixio.bit.html">nixio.bit</a>
169 </li>
170
171 <li>
172 <a href="../modules/nixio.crypto.html">nixio.crypto</a>
173 </li>
174
175 <li>
176 <a href="../modules/nixio.fs.html">nixio.fs</a>
177 </li>
178
179 </ul>
180
181
182
183 <!-- File list -->
184
185
186
187
188
189
190
191 </div><!-- id="navigation" -->
192
193 <div id="content">
194
195 <h1>Object Instance <code>nixio.Socket</code></h1>
196
197 <p>
198 Socket Object.
199 Supports IPv4, IPv6 and UNIX (POSIX only) families.</p>
200
201
202
203
204
205
206
207 <h2>Functions</h2>
208 <table class="function_list">
209
210 <tr>
211 <td class="name" nowrap><a href="#Socket.accept">Socket:accept</a>&nbsp;()</td>
212 <td class="summary">
213 Accept a connection on the socket.</td>
214 </tr>
215
216 <tr>
217 <td class="name" nowrap><a href="#Socket.bind">Socket:bind</a>&nbsp;(host, port)</td>
218 <td class="summary">
219 Bind the socket to a network address.</td>
220 </tr>
221
222 <tr>
223 <td class="name" nowrap><a href="#Socket.close">Socket:close</a>&nbsp;()</td>
224 <td class="summary">
225 Close the socket.</td>
226 </tr>
227
228 <tr>
229 <td class="name" nowrap><a href="#Socket.connect">Socket:connect</a>&nbsp;(host, port)</td>
230 <td class="summary">
231 Connect the socket to a network address.</td>
232 </tr>
233
234 <tr>
235 <td class="name" nowrap><a href="#Socket.fileno">Socket:fileno</a>&nbsp;()</td>
236 <td class="summary">
237 Get the number of the filedescriptor.</td>
238 </tr>
239
240 <tr>
241 <td class="name" nowrap><a href="#Socket.getopt">Socket:getopt</a>&nbsp;(level, option)</td>
242 <td class="summary">
243 Get a socket option.</td>
244 </tr>
245
246 <tr>
247 <td class="name" nowrap><a href="#Socket.getpeername">Socket:getpeername</a>&nbsp;()</td>
248 <td class="summary">
249 Get the peer address of a socket.</td>
250 </tr>
251
252 <tr>
253 <td class="name" nowrap><a href="#Socket.getsockname">Socket:getsockname</a>&nbsp;()</td>
254 <td class="summary">
255 Get the local address of a socket.</td>
256 </tr>
257
258 <tr>
259 <td class="name" nowrap><a href="#Socket.listen">Socket:listen</a>&nbsp;(backlog)</td>
260 <td class="summary">
261 Listen for connections on the socket.</td>
262 </tr>
263
264 <tr>
265 <td class="name" nowrap><a href="#Socket.read ">Socket:read </a>&nbsp;(length)</td>
266 <td class="summary">
267 Receive a message on the socket (This is an alias for recv).</td>
268 </tr>
269
270 <tr>
271 <td class="name" nowrap><a href="#Socket.recv ">Socket:recv </a>&nbsp;(length)</td>
272 <td class="summary">
273 Receive a message on the socket.</td>
274 </tr>
275
276 <tr>
277 <td class="name" nowrap><a href="#Socket.recvfrom">Socket:recvfrom</a>&nbsp;(length)</td>
278 <td class="summary">
279 Receive a message on the socket including the senders source address.</td>
280 </tr>
281
282 <tr>
283 <td class="name" nowrap><a href="#Socket.send">Socket:send</a>&nbsp;(buffer, offset, length)</td>
284 <td class="summary">
285 Send a message on the socket.</td>
286 </tr>
287
288 <tr>
289 <td class="name" nowrap><a href="#Socket.sendto">Socket:sendto</a>&nbsp;(buffer, host, port, offset, length)</td>
290 <td class="summary">
291 Send a message on the socket specifying the destination.</td>
292 </tr>
293
294 <tr>
295 <td class="name" nowrap><a href="#Socket.setblocking">Socket:setblocking</a>&nbsp;(blocking)</td>
296 <td class="summary">
297 Set the blocking mode of the socket.</td>
298 </tr>
299
300 <tr>
301 <td class="name" nowrap><a href="#Socket.setopt">Socket:setopt</a>&nbsp;(level, option, value)</td>
302 <td class="summary">
303 Set a socket option.</td>
304 </tr>
305
306 <tr>
307 <td class="name" nowrap><a href="#Socket.shutdown">Socket:shutdown</a>&nbsp;(how)</td>
308 <td class="summary">
309 Shut down part of a full-duplex connection.</td>
310 </tr>
311
312 <tr>
313 <td class="name" nowrap><a href="#Socket.write">Socket:write</a>&nbsp;(buffer, offset, length)</td>
314 <td class="summary">
315 Send a message on the socket (This is an alias for send).</td>
316 </tr>
317
318 </table>
319
320
321
322
323
324
325 <br/>
326 <br/>
327
328
329 <h2><a name="functions"></a>Functions</h2>
330 <dl class="function">
331
332
333
334 <dt><a name="Socket.accept"></a><strong>Socket:accept</strong>&nbsp;()</dt>
335 <dd>
336
337 Accept a connection on the socket.
338
339
340
341
342
343
344
345 <h3>Return values:</h3>
346 <ol>
347
348 <li>Socket Object
349
350 <li>Peer IP-Address
351
352 <li>Peer Port
353
354 </ol>
355
356
357
358 </dd>
359
360
361
362
363 <dt><a name="Socket.bind"></a><strong>Socket:bind</strong>&nbsp;(host, port)</dt>
364 <dd>
365
366 Bind the socket to a network address.
367
368
369 <h3>Parameters</h3>
370 <ul>
371
372 <li>
373 host: Host (optional, default: all addresses)
374 </li>
375
376 <li>
377 port: Port or service description
378 </li>
379
380 </ul>
381
382
383
384
385 <h3>Usage</h3>
386 <ul>
387
388 <li>This function calls getaddrinfo() and bind() but NOT listen().
389
390 <li>If <em>host</em> is a domain name it will be looked up and bind()
391 tries the IP-Addresses in the order returned by the DNS resolver
392 until the bind succeeds.
393
394 <li>UNIX sockets ignore the <em>port</em>,
395 and interpret <em>host</em> as a socket path.
396
397 </ul>
398
399
400
401 <h3>Return value:</h3>
402 true
403
404
405
406 </dd>
407
408
409
410
411 <dt><a name="Socket.close"></a><strong>Socket:close</strong>&nbsp;()</dt>
412 <dd>
413
414 Close the socket.
415
416
417
418
419
420
421
422 <h3>Return value:</h3>
423 true
424
425
426
427 </dd>
428
429
430
431
432 <dt><a name="Socket.connect"></a><strong>Socket:connect</strong>&nbsp;(host, port)</dt>
433 <dd>
434
435 Connect the socket to a network address.
436
437
438 <h3>Parameters</h3>
439 <ul>
440
441 <li>
442 host: Hostname or IP-Address (optional, default: localhost)
443 </li>
444
445 <li>
446 port: Port or service description
447 </li>
448
449 </ul>
450
451
452
453
454 <h3>Usage</h3>
455 <ul>
456
457 <li>This function calls getaddrinfo() and connect().
458
459 <li>If <em>host</em> is a domain name it will be looked up and connect()
460 tries the IP-Addresses in the order returned by the DNS resolver
461 until the connect succeeds.
462
463 <li>UNIX sockets ignore the <em>port</em>,
464 and interpret <em>host</em> as a socket path.
465
466 </ul>
467
468
469
470 <h3>Return value:</h3>
471 true
472
473
474
475 </dd>
476
477
478
479
480 <dt><a name="Socket.fileno"></a><strong>Socket:fileno</strong>&nbsp;()</dt>
481 <dd>
482
483 Get the number of the filedescriptor.
484
485
486
487
488
489
490
491 <h3>Return value:</h3>
492 file descriptor number
493
494
495
496 </dd>
497
498
499
500
501 <dt><a name="Socket.getopt"></a><strong>Socket:getopt</strong>&nbsp;(level, option)</dt>
502 <dd>
503
504 Get a socket option.
505
506
507 <h3>Parameters</h3>
508 <ul>
509
510 <li>
511 level: Level ["socket", "tcp", "ip", "ipv6"]
512 </li>
513
514 <li>
515 option: Option ["keepalive", "reuseaddr", "sndbuf", "rcvbuf",
516 "priority", "broadcast", "linger", "sndtimeo", "rcvtimeo", "dontroute",
517 "bindtodevice", "error", "oobinline", "cork" (TCP), "nodelay" (TCP),
518 "mtu" (IP, IPv6), "hdrincl" (IP), "multicast_ttl" (IP), "multicast_loop"
519 (IP, IPv6), "multicast_if" (IP, IPv6), "v6only" (IPv6), "multicast_hops"
520 (IPv6), "add_membership" (IP, IPv6), "drop_membership" (IP, IPv6)]
521 </li>
522
523 </ul>
524
525
526
527
528
529
530 <h3>Return value:</h3>
531 Value
532
533
534
535 </dd>
536
537
538
539
540 <dt><a name="Socket.getpeername"></a><strong>Socket:getpeername</strong>&nbsp;()</dt>
541 <dd>
542
543 Get the peer address of a socket.
544
545
546
547
548
549
550
551 <h3>Return values:</h3>
552 <ol>
553
554 <li>IP-Address
555
556 <li>Port
557
558 </ol>
559
560
561
562 </dd>
563
564
565
566
567 <dt><a name="Socket.getsockname"></a><strong>Socket:getsockname</strong>&nbsp;()</dt>
568 <dd>
569
570 Get the local address of a socket.
571
572
573
574
575
576
577
578 <h3>Return values:</h3>
579 <ol>
580
581 <li>IP-Address
582
583 <li>Port
584
585 </ol>
586
587
588
589 </dd>
590
591
592
593
594 <dt><a name="Socket.listen"></a><strong>Socket:listen</strong>&nbsp;(backlog)</dt>
595 <dd>
596
597 Listen for connections on the socket.
598
599
600 <h3>Parameters</h3>
601 <ul>
602
603 <li>
604 backlog: Length of queue for pending connections
605 </li>
606
607 </ul>
608
609
610
611
612
613
614 <h3>Return value:</h3>
615 true
616
617
618
619 </dd>
620
621
622
623
624 <dt><a name="Socket.read "></a><strong>Socket:read </strong>&nbsp;(length)</dt>
625 <dd>
626
627 Receive a message on the socket (This is an alias for recv).
628 See the recvfrom description for more details.
629
630
631 <h3>Parameters</h3>
632 <ul>
633
634 <li>
635 length: Amount of data to read (in Bytes).
636 </li>
637
638 </ul>
639
640
641
642
643
644
645 <h3>Return value:</h3>
646 buffer containing data successfully read
647
648
649
650 <h3>See also:</h3>
651 <ul>
652
653 <li><a href="#Socket.recvfrom">
654 Socket:recvfrom
655 </a>
656
657 </ul>
658
659 </dd>
660
661
662
663
664 <dt><a name="Socket.recv "></a><strong>Socket:recv </strong>&nbsp;(length)</dt>
665 <dd>
666
667 Receive a message on the socket.
668 This function is identical to recvfrom except that it does not return
669 the sender's source address. See the recvfrom description for more details.
670
671
672 <h3>Parameters</h3>
673 <ul>
674
675 <li>
676 length: Amount of data to read (in Bytes).
677 </li>
678
679 </ul>
680
681
682
683
684
685
686 <h3>Return value:</h3>
687 buffer containing data successfully read
688
689
690
691 <h3>See also:</h3>
692 <ul>
693
694 <li><a href="#Socket.recvfrom">
695 Socket:recvfrom
696 </a>
697
698 </ul>
699
700 </dd>
701
702
703
704
705 <dt><a name="Socket.recvfrom"></a><strong>Socket:recvfrom</strong>&nbsp;(length)</dt>
706 <dd>
707
708 Receive a message on the socket including the senders source address.
709
710
711 <h3>Parameters</h3>
712 <ul>
713
714 <li>
715 length: Amount of data to read (in Bytes).
716 </li>
717
718 </ul>
719
720
721
722
723 <h3>Usage</h3>
724 <ul>
725
726 <li><strong>Warning:</strong> It is not guaranteed that all requested data
727 is read at once.
728 You have to check the return value - the length of the buffer actually read -
729 or use the safe IO functions in the high-level IO utility module.
730
731 <li>The length of the return buffer is limited by the (compile time)
732 nixio buffersize which is <em>nixio.const.buffersize</em> (8192 by default).
733 Any read request greater than that will be safely truncated to this value.
734
735 </ul>
736
737
738
739 <h3>Return values:</h3>
740 <ol>
741
742 <li>buffer containing data successfully read
743
744 <li>host IP-Address of the sender
745
746 <li>port Port of the sender
747
748 </ol>
749
750
751
752 </dd>
753
754
755
756
757 <dt><a name="Socket.send"></a><strong>Socket:send</strong>&nbsp;(buffer, offset, length)</dt>
758 <dd>
759
760 Send a message on the socket.
761 This function is identical to sendto except for the missing destination
762 parameters. See the sendto description for a detailed description.
763
764
765 <h3>Parameters</h3>
766 <ul>
767
768 <li>
769 buffer: Buffer holding the data to be written.
770 </li>
771
772 <li>
773 offset: Offset to start reading the buffer from. (optional)
774 </li>
775
776 <li>
777 length: Length of chunk to read from the buffer. (optional)
778 </li>
779
780 </ul>
781
782
783
784
785
786
787 <h3>Return value:</h3>
788 number of bytes written
789
790
791
792 <h3>See also:</h3>
793 <ul>
794
795 <li><a href="#Socket.sendto">
796 Socket:sendto
797 </a>
798
799 </ul>
800
801 </dd>
802
803
804
805
806 <dt><a name="Socket.sendto"></a><strong>Socket:sendto</strong>&nbsp;(buffer, host, port, offset, length)</dt>
807 <dd>
808
809 Send a message on the socket specifying the destination.
810
811
812 <h3>Parameters</h3>
813 <ul>
814
815 <li>
816 buffer: Buffer holding the data to be written.
817 </li>
818
819 <li>
820 host: Target IP-Address
821 </li>
822
823 <li>
824 port: Target Port
825 </li>
826
827 <li>
828 offset: Offset to start reading the buffer from. (optional)
829 </li>
830
831 <li>
832 length: Length of chunk to read from the buffer. (optional)
833 </li>
834
835 </ul>
836
837
838
839
840 <h3>Usage</h3>
841 <ul>
842
843 <li><strong>Warning:</strong> It is not guaranteed that all data
844 in the buffer is written at once.
845 You have to check the return value - the number of bytes actually written -
846 or use the safe IO functions in the high-level IO utility module.
847
848 <li>Unlike standard Lua indexing the lowest offset and default is 0.
849
850 </ul>
851
852
853
854 <h3>Return value:</h3>
855 number of bytes written
856
857
858
859 </dd>
860
861
862
863
864 <dt><a name="Socket.setblocking"></a><strong>Socket:setblocking</strong>&nbsp;(blocking)</dt>
865 <dd>
866
867 Set the blocking mode of the socket.
868
869
870 <h3>Parameters</h3>
871 <ul>
872
873 <li>
874 blocking: (boolean)
875 </li>
876
877 </ul>
878
879
880
881
882
883
884 <h3>Return value:</h3>
885 true
886
887
888
889 </dd>
890
891
892
893
894 <dt><a name="Socket.setopt"></a><strong>Socket:setopt</strong>&nbsp;(level, option, value)</dt>
895 <dd>
896
897 Set a socket option.
898
899
900 <h3>Parameters</h3>
901 <ul>
902
903 <li>
904 level: Level ["socket", "tcp", "ip", "ipv6"]
905 </li>
906
907 <li>
908 option: Option ["keepalive", "reuseaddr", "sndbuf", "rcvbuf",
909 "priority", "broadcast", "linger", "sndtimeo", "rcvtimeo", "dontroute",
910 "bindtodevice", "error", "oobinline", "cork" (TCP), "nodelay" (TCP),
911 "mtu" (IP, IPv6), "hdrincl" (IP), "multicast_ttl" (IP), "multicast_loop"
912 (IP, IPv6), "multicast_if" (IP, IPv6), "v6only" (IPv6), "multicast_hops"
913 (IPv6), "add_membership" (IP, IPv6), "drop_membership" (IP, IPv6)]
914 </li>
915
916 <li>
917 value: Value
918 </li>
919
920 </ul>
921
922
923
924
925
926
927 <h3>Return value:</h3>
928 true
929
930
931
932 </dd>
933
934
935
936
937 <dt><a name="Socket.shutdown"></a><strong>Socket:shutdown</strong>&nbsp;(how)</dt>
938 <dd>
939
940 Shut down part of a full-duplex connection.
941
942
943 <h3>Parameters</h3>
944 <ul>
945
946 <li>
947 how: (optional, default: rdwr) ["rdwr", "rd", "wr"]
948 </li>
949
950 </ul>
951
952
953
954
955
956
957 <h3>Return value:</h3>
958 true
959
960
961
962 </dd>
963
964
965
966
967 <dt><a name="Socket.write"></a><strong>Socket:write</strong>&nbsp;(buffer, offset, length)</dt>
968 <dd>
969
970 Send a message on the socket (This is an alias for send).
971 See the sendto description for a detailed description.
972
973
974 <h3>Parameters</h3>
975 <ul>
976
977 <li>
978 buffer: Buffer holding the data to be written.
979 </li>
980
981 <li>
982 offset: Offset to start reading the buffer from. (optional)
983 </li>
984
985 <li>
986 length: Length of chunk to read from the buffer. (optional)
987 </li>
988
989 </ul>
990
991
992
993
994
995
996 <h3>Return value:</h3>
997 number of bytes written
998
999
1000
1001 <h3>See also:</h3>
1002 <ul>
1003
1004 <li><a href="#Socket.sendto">
1005 Socket:sendto
1006 </a>
1007
1008 </ul>
1009
1010 </dd>
1011
1012
1013 </dl>
1014
1015
1016
1017
1018
1019 </div> <!-- id="content" -->
1020
1021 </div> <!-- id="main" -->
1022
1023 <div id="about">
1024 <p><a href="http://validator.w3.org/check?uri=referer"><img src="http://www.w3.org/Icons/valid-xhtml10" alt="Valid XHTML 1.0!" height="31" width="88" /></a></p>
1025 </div> <!-- id="about" -->
1026
1027 </div> <!-- id="container" -->
1028 </body>
1029 </html>