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