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