documentation: regenerate documents from current code base
[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.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>