Sys/Socket.pm untested

filter: Statementstmt n/a Branchbran n/a Conditioncond n/a MC/DCmcdc n/a Subroutinesub n/a Podpod n/a SCAR -
1 package SPVM::Sys::Socket;
2  
3 1;
4  
5 =head1 Name
6  
7 SPVM::Sys::Socket - System Calls for Sockets
8  
9 =head1 Description
10  
11 Sys::Socket class in L<SPVM> has methods to call system calls for sockets.
12  
13 =head1 Usage
14
15 use Sys::Socket;
16 use Sys::Socket::Constant as SOCKET;
17
18 my $socket_fd = Sys::Socket->socket(SOCKET->AF_INET, SOCKET->SOCK_STREAM, 0);
19  
20 =head1 Class Methods
21  
22 =head2 htonl
23  
24 C<static method htonl : int ($hostlong : int);>
25  
26 Calls the L<htonl|https://linux.die.net/man/3/htonl> function and returns its return value.
27  
28 =head2 htons
29  
30 C<static method htons : short ($hostshort : short);>
31  
32 Calls the L<htons|https://linux.die.net/man/3/htons> function and returns its return value.
33  
34 =head2 ntohl
35  
36 C<static method ntohl : int ($netlong : int);>
37  
38 Calls the L<ntohl|https://linux.die.net/man/3/ntohl> function and returns its return value.
39  
40 =head2 ntohs
41  
42 C<static method ntohs : short ($netshort : short);>
43  
44 Calls the L<ntohs|https://linux.die.net/man/3/ntohs> function and returns its return value.
45  
46 =head2 inet_aton
47  
48 C<static method inet_aton : int ($cp : string, $inp : L<Sys::Socket::In_addr|SPVM::Sys::Socket::In_addr>);>
49  
50 Calls the L<inet_aton|https://linux.die.net/man/3/inet_aton> function and returns its return value.
51  
52 Excetpions:
53  
54 $cp must be defined. Otherwise an excetpion is thrown.
55  
56 $inp must be defined. Otherwise an excetpion is thrown.
57  
58 If the got address is not a valid network, an excetpion is thrownn with C<eval_error_id> set to the basic type ID of the L<Sys::Socket::Error::InetInvalidNetworkAddress> class.
59  
60 If the inet_aton function failed, an excetpion is thrownn with C<eval_error_id> set to the basic type ID of the L<Error::System|SPVM::Error::System> class.
61  
62 =head2 inet_ntoa
63  
64 C<static method inet_ntoa : string ($in : L<Sys::Socket::In_addr|SPVM::Sys::Socket::In_addr>);>
65  
66 Calls the L<inet_ntoa|https://linux.die.net/man/3/inet_ntoa> function and returns its return value.
67  
68 Excetpions:
69  
70 $in address must be defined. Otherwise an excetpion is thrown.
71  
72 If the inet_ntoa function failed, an excetpion is thrownn with C<eval_error_id> set to the basic type ID of the L<Sys::Socket::Error::InetInvalidNetworkAddress> class.
73  
74 =head2 inet_pton
75  
76 C<static method inet_pton : int ($af : int, $src : string, $dst : L<Sys::Socket::In_addr_base|SPVM::Sys::Socket::In_addr_base>);>
77  
78 Calls the L<inet_pton|https://linux.die.net/man/3/inet_pton> function and returns its return value.
79  
80 See L<Sys::Socket::Constant|SPVM::Sys::Socket::Constant> about constant values given to $af.
81  
82 Exceptions:
83  
84 $af must be AF_INET or AF_INET6. Otherwise an excetpion is thrown.
85  
86 $dst must be defined. Otherwise an excetpion is thrown.
87  
88 If $af must be AF_INET, $dst must be the Sys::Socket::In_addr class. Otherwise an excetpion is thrown.
89  
90 If $af must be AF_INET6, $dst must be the Sys::Socket::In6_addr class. Otherwise an excetpion is thrown.
91  
92 If the type of $dst is invalid, otherwise an excetpion is thrown.
93  
94 If the got address is not a valid network, an excetpion is thrownn with C<eval_error_id> set to the basic type ID of the L<Sys::Socket::Error::InetInvalidNetworkAddress> class.
95  
96 If the inet_pton function failed, an excetpion is thrownn with C<eval_error_id> set to the basic type ID of the L<Error::System|SPVM::Error::System> class.
97  
98 =head2 inet_ntop
99  
100 C<static method inet_ntop : mutable string ($af : int, $src : L<Sys::Socket::In_addr_base|SPVM::Sys::Socket::In_addr_base>, $dst : mutable string, $size : int);>
101  
102 Calls the L<inet_ntop|https://linux.die.net/man/3/inet_ntop> function and returns its return value.
103  
104 See L<Sys::Socket::Constant|SPVM::Sys::Socket::Constant> about constant values given to $af.
105  
106 Excetpions:
107  
108 $af must be AF_INET or AF_INET6. Otherwise an excetpion is thrown.
109  
110 $src must be defined. Otherwise an excetpion is thrown.
111  
112 $dst must be defined. Otherwise an excetpion is thrown.
113  
114 If the inet_ntop function failed, an excetpion is thrownn with C<eval_error_id> set to the basic type ID of the L<Error::System|SPVM::Error::System> class.
115  
116 =head2 socket
117  
118 C<static method socket : int ($domain : int, $type : int, $protocol : int);>
119  
120 Calls the L<socket|https://linux.die.net/man/2/socket> function and returns its return value.
121  
122 See L<Sys::Socket::Constant|SPVM::Sys::Socket::Constant> about constant values given to $domain, $type, and $protocal.
123  
124 Excetpions:
125  
126 If the socket function failed, an excetpion is thrownn with C<eval_error_id> set to the basic type ID of the L<Error::System|SPVM::Error::System> class.
127  
128 =head2 connect
129  
130 C<static method connect : int ($sockfd : int, $addr : L<Sys::Socket::Sockaddr|SPVM::Sys::Socket::Sockaddr>, $addrlen : int);>
131  
132 Calls the L<connect|https://linux.die.net/man/2/connect> function and returns its return value.
133  
134 Excetpions:
135  
136 $addr must be defined. Otherwise an excetpion is thrown.
137  
138 If the connect function failed, an excetpion is thrownn with C<eval_error_id> set to the basic type ID of the L<Error::System|SPVM::Error::System> class.
139  
140 =head2 bind
141  
142 C<static method bind : int ($sockfd : int, $addr : L<Sys::Socket::Sockaddr|SPVM::Sys::Socket::Sockaddr>, $addrlen : int);>
143  
144 Calls the L<bind|https://linux.die.net/man/2/bind> function and returns its return value.
145  
146 Excetpions:
147  
148 $addr must be defined. Otherwise an excetpion is thrown.
149  
150 If the bind function failed, an excetpion is thrownn with C<eval_error_id> set to the basic type ID of the L<Error::System|SPVM::Error::System> class.
151  
152 =head2 accept
153  
154 C<static method accept : int ($sockfd : int, $addr : L<Sys::Socket::Sockaddr|SPVM::Sys::Socket::Sockaddr>, $addrlen_ref : int*);>
155  
156 Calls the L<accept|https://linux.die.net/man/2/accept> function and returns its return value.
157  
158 Exceptions:
159  
160 $addr must be defined. Otherwise an excetpion is thrown.
161  
162 The reference of the output address length $addrlen_ref must be defined. Otherwise an exception is thrown.
163  
164 If the accept function failed, an excetpion is thrownn with C<eval_error_id> set to the basic type ID of the L<Error::System|SPVM::Error::System> class.
165  
166 =head2 listen
167  
168 C<static method listen : int ($sockfd : int, $backlog : int);>
169  
170 Calls the L<listen|https://linux.die.net/man/2/listen> function and returns its return value.
171  
172 Excetpions:
173  
174 If the listen function failed, an excetpion is thrownn with C<eval_error_id> set to the basic type ID of the L<Error::System|SPVM::Error::System> class.
175  
176 =head2 shutdown
177  
178 C<static method shutdown : int ($sockfd : int, $how : int);>
179  
180 Calls the L<shutdown|https://linux.die.net/man/2/shutdown> function and returns its return value.
181  
182 See L<Sys::Socket::Constant|SPVM::Sys::Socket::Constant> about constant values given to $how.
183  
184 Excetpions:
185  
186 If the shutdown function failed, an excetpion is thrownn with C<eval_error_id> set to the basic type ID of the L<Error::System|SPVM::Error::System> class.
187  
188 =head2 closesocket
189  
190 C<static method closesocket : int ($fd : int);>
191  
192 Calls the L<closesocket|https://learn.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-closesocket> function and returns its return value.
193  
194 Excetpions:
195  
196 If the closesocket function failed, an excetpion is thrownn with C<eval_error_id> set to the basic type ID of the L<Error::System|SPVM::Error::System> class.
197  
198 =head2 close
199  
200 C<static method close : int ($fd : int);>
201  
202 Calls the L</"closesocket"> method in Windows.
203  
204 Calls L<the#close|SPVM::the/"close"> method Sys::IO class in other OSs.
205  
206 =head2 recv
207  
208 C<static method recv : int ($sockfd : int, $buf : mutable string, $len : int, $flags : int, $buf_offset : int = 0);>
209  
210 Calls the L<recv|https://linux.die.net/man/2/recv> function and returns its return value.
211  
212 Excetpions:
213  
214 $buf must be defined. Otherwise an excetpion is thrown.
215  
216 $len must be less than the length of $buf - $buf_offset. Otherwise an excetpion is thrown.
217  
218 If the recv function failed, an excetpion is thrownn with C<eval_error_id> set to the basic type ID of the L<Error::System|SPVM::Error::System> class.
219  
220 =head2 recvfrom
221  
222 C<static method recvfrom : int ($sockfd : int, $buf : mutable string, $len : int, $flags : int, $src_addr : Sys::Socket::Sockaddr, $addrlen_ref : int*, $buf_offset : int = 0);>
223  
224 Calls the L<recvfromv|https://linux.die.net/man/2/recvfrom> function and returns its return value.
225  
226 Excetpions:
227  
228 $buf must be defined. Otherwise an excetpion is thrown.
229  
230 $len must be less than the length of $buf - $buf_offset. Otherwise an excetpion is thrown.
231  
232 The reference of the output address length $addrlen_ref must be defined. Otherwise an exception is thrown.
233  
234 If the recv function failed, an excetpion is thrownn with C<eval_error_id> set to the basic type ID of the L<Error::System|SPVM::Error::System> class.
235  
236 =head2 send
237  
238 C<static method send : int ($sockfd : int, $buf : string, $len : int, $flags : int, $buf_offset : int = 0);>
239  
240 Calls the L<send|https://linux.die.net/man/2/send> function and returns its return value.
241  
242 Excetpions:
243  
244 $buf must be defined. Otherwise an excetpion is thrown.
245  
246 $len must be less than the length of $buf - $buf_offset. Otherwise an excetpion is thrown.
247  
248 If the send function failed, an excetpion is thrownn with C<eval_error_id> set to the basic type ID of the L<Error::System|SPVM::Error::System> class.
249  
250 =head2 sendto
251  
252 C<static method sendto : int ($sockfd : int, $buf : string, $len : int, $flags : int, $addr : L<Sys::Socket::Sockaddr|SPVM::Sys::Socket::Sockaddr>, $addrlen : int, $buf_offset : int = 0);>
253  
254 Calls the L<sendto|https://linux.die.net/man/2/sendto> function and returns its return value.
255  
256 Excetpions:
257  
258 $buf must be defined. Otherwise an excetpion is thrown.
259  
260 $len must be less than the length of $buf - $buf_offset. Otherwise an excetpion is thrown.
261  
262 If the send function failed, an excetpion is thrownn with C<eval_error_id> set to the basic type ID of the L<Error::System|SPVM::Error::System> class.
263  
264 =head2 getpeername
265  
266 C<static method getpeername : int ($sockfd : int, $addr : L<Sys::Socket::Sockaddr|SPVM::Sys::Socket::Sockaddr>, $addrlen_ref : int*);>
267  
268 Calls the L<getpeername|https://linux.die.net/man/2/getpeername> function and returns its return value.
269  
270 Exceptions:
271  
272 $addr must be defined. Otherwise an exception is thrown.
273  
274 The reference of the output address length $addrlen_ref must be defined. Otherwise an exception is thrown.
275  
276 If the getpeername function failed, an exception is thrown with C<eval_error_id> set to the basic type ID of the L<Error::System|SPVM::Error::System> class.
277  
278 Excetpions:
279  
280 =head2 getsockname
281  
282 C<static method getsockname : int ($sockfd : int, $addr : L<Sys::Socket::Sockaddr|SPVM::Sys::Socket::Sockaddr>, $addrlen_ref : int*);>
283  
284 Calls the L<getsockname|https://linux.die.net/man/2/getsockname> function and returns its return value.
285  
286 Excetpions:
287  
288 $addr must be defined. Otherwise an exception is thrown.
289  
290 The reference of the output address length $addrlen_ref must be defined. Otherwise an exception is thrown.
291  
292 If the getsockname function failed, an exception is thrown with C<eval_error_id> set to the basic type ID of the L<Error::System|SPVM::Error::System> class.
293  
294 Excetpions:
295  
296 =head2 getsockopt
297  
298 C<static method getsockopt : int ($sockfd : int, $level : int, $optname : int, $optval : mutable string, $optlen_ref : int*);>
299  
300 Calls the L<getsockopt|https://linux.die.net/man/2/getsockopt> function and returns its return value.
301  
302 See L<Sys::Socket::Constant|SPVM::Sys::Socket::Constant> about constant values given to $level and $optname.
303  
304 Exceptions:
305  
306 $optval must be defined. Otherwise an exception is thrown.
307  
308 The referred value of $optlen_ref must be greater than or equal to 0. Otherwise an exception is thrown.
309  
310 The referred value of $optlen_ref must be less than or equal to the length of $optval. Otherwise an exception is thrown.
311  
312 If the getsockopt function failed, an exception is thrown with C<eval_error_id> set to the basic type ID of the L<Error::System|SPVM::Error::System> class.
313  
314 =head2 setsockopt
315  
316 C<static method setsockopt : int ($sockfd : int, $level : int, $optname : int, $optval : string, $optlen : int);>
317  
318 Calls the L<setsockopt|https://linux.die.net/man/2/setsockopt> function and returns its return value.
319  
320 See L<Sys::Socket::Constant|SPVM::Sys::Socket::Constant> about constant values given to $level and $optname.
321  
322 Exceptions:
323  
324 $optval must be defined. Otherwise an exception is thrown.
325  
326 $optlen must be greater than or equal to 0. Otherwise an exception is thrown.
327  
328 $optlen must be less than or equal to the length of $optval. Otherwise an exception is thrown.
329  
330 If the setsockopt function failed, an exception is thrown with C<eval_error_id> set to the basic type ID of the L<Error::System|SPVM::Error::System> class.
331  
332 =head2 socketpair
333  
334 C<static method socketpair : int ($domain : int, $type : int, $protocol : int, $sv : int[]);>
335  
336 Calls the L<socketpair|https://linux.die.net/man/2/socketpair> function and returns its return value.
337  
338 See L<Sys::Socket::Constant|SPVM::Sys::Socket::Constant> about constant values given to $domain, $type, and $protocol.
339  
340 Exceptions:
341  
342 $sv must be defined. Otherwise an exception is thrown.
343  
344 The length of $sv must be greater than or equal to 2. Otherwise an exception is thrown.
345  
346 If the socketpair function failed, an exception is thrown with C<eval_error_id> set to the basic type ID of the L<Error::System|SPVM::Error::System> class.
347  
348 =head2 getaddrinfo
349  
350 C<static method getaddrinfo : int ($node : string, $service : string, $hints : L<Sys::Socket::Addrinfo|SPVM::Sys::Socket::Addrinfo>, $res_ref : L<Sys::Socket::AddrinfoLinkedList|SPVM::Sys::Socket::AddrinfoLinkedList>[]);>
351  
352 Calls the L<getaddrinfo|https://linux.die.net/man/3/getaddrinfo> function and returns its return value.
353  
354 Exceptions:
355  
356 $res_array must be defined. Otherwise an exception is thrown.
357  
358 The length of $res_array must be equal to 1.
359  
360 If the getnameinfo function failed, an exception is thrown with C<eval_error_id> set to the basic type ID of the L<Error::System|SPVM::Error::System> class.
361  
362 =head2 getnameinfo
363  
364 C<static method getnameinfo : int ($sa : L<Sys::Socket::Sockaddr|SPVM::Sys::Socket::Sockaddr>, $salen : int, $host : mutable string, $hostlen : int, $serv : mutable string, $servlen : int, $flags : int);>
365  
366 Calls the L<getnameinfo|https://linux.die.net/man/3/getaddrinfo> function and returns its return value.
367  
368 Excetpions:
369  
370 $sa must be defined. Otherwise an exception is thrown.
371  
372 If the getnameinfo function failed, an exception is thrown with C<eval_error_id> set to the basic type ID of the L<Error::System|SPVM::Error::System> class.
373  
374 =head2 gai_strerror
375  
376 C<static method gai_strerror : string($errcode : int);>
377  
378 Calls the L<gai_strerror|https://linux.die.net/man/3/gai_strerror> function and returns its return value.
379  
380 Excepsions:
381  
382 If the gai_strerror function failed, an exception is thrown with C<eval_error_id> set to the basic type ID of the L<Error::System|SPVM::Error::System> class.
383  
384 =head2 sockatmark
385  
386 C<static method sockatmark : int ($sockfd : int);>
387  
388 Calls the L<sockatmark|https://linux.die.net/man/3/sockatmark> function and returns its return value.
389  
390 Excepsions:
391  
392 If the sockatmark function failed, an exception is thrown with C<eval_error_id> set to the basic type ID of the L<Error::System|SPVM::Error::System> class.
393  
394 =head2 win_set_tcp_keepalive
395  
396 C<static method win_set_tcp_keepalive : int ($sockfd : int, $onoff : int, $keepalivetime_ms : int, $keepaliveinterval_ms : int);>
397  
398 Sets the TCP keep-alive settings (C<SIO_KEEPALIVE_VALS>) on Windows. This method calls the L<WSAIoctl|https://learn.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-wsaioctl> function with the C<SIO_KEEPALIVE_VALS> control code.
399  
400 For more information about the parameters, see the L<tcp_keepalive structure|https://learn.microsoft.com/en-us/windows/win32/api/mstcpip/ns-mstcpip-tcp_keepalive>.
401  
402 Return Value:
403  
404 If the function succeeds, the return value is 0.
405  
406 Exceptions:
407  
408 This method is only supported on Windows. If it is called on other systems, an exception is thrown with C<eval_error_id> set to the basic type ID of the L<Error::NotSupported|SPVM::Error::NotSupported> class.
409  
410 If the WSAIoctl function failed, an exception is thrown with C<eval_error_id> set to the basic type ID of the L<Error::System|SPVM::Error::System> class.
411  
412 =head1 See Also
413  
414 =over 2
415  
416 =item * L<Sys|SPVM::Sys>
417  
418 =back
419  
420 =head1 Copyright & License
421  
422 Copyright (c) 2023 Yuki Kimoto
423  
424 MIT License
425