Sys/Socket/Util.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::Util;
2  
3  
4  
5 1;
6  
7 =head1 Name
8  
9 SPVM::Sys::Socket::Util - Socket Utilities
10  
11 =head1 Description
12  
13 Sys::Socket::Util class in L<SPVM> has methods for socket utilities.
14  
15 =head1 Usage
16  
17 use Sys::Socket::Util;
18  
19 =head1 Class Methods
20  
21 =head2 inet_aton
22  
23 C<static method inet_aton : L<Sys::Socket::In_addr|SPVM::Sys::Socket::In_addr> ($address : string);>
24  
25 Creates a new L<Sys::Socket::In_addr|SPVM::Sys::Socket::In_addr> object and calls L<Sys::Socket#inet_aton|SPVM::Sys::Socket/"inet_aton"> method with it, and returns it.
26  
27 =head2 inet_ntoa
28  
29 C<static method inet_ntoa : string ($in_addr : Sys::Socket::In_addr);>
30  
31 Calls L<Sys::Socket#inet_ntoa|SPVM::Sys::Socket/"inet_ntoa"> method, and returns its return value.
32  
33 =head2 inet_pton
34  
35 C<static method inet_pton : L<Sys::Socket::In_addr_base|SPVM::Sys::Socket::In_addr_base> ($family : int, $address : string);>
36  
37 Creates a new L<Sys::Socket::In_addr|SPVM::Sys::Socket::In_addr> object or a new L<Sys::Socket::In6_addr|SPVM::Sys::Socket::In6_addr> according to the address family $family.
38  
39 And calls L<Sys::Socket#inet_aton|SPVM::Sys::Socket/"inet_aton"> method with it, and returns it.
40  
41 Excetpions:
42  
43 If the address family $family is not available, an excetpion is thrown.
44  
45 =head2 inet_ntop
46  
47 C<static method inet_ntop : string ($family : int, $in_addr : L<Sys::Socket::In_addr_base|SPVM::Sys::Socket::In_addr_base>);>
48  
49 Calls L<Sys::Socket#inet_ntop|SPVM::Sys::Socket/"inet_ntop"> method given enough address buffer $dst.
50  
51 And the got address $dst is truncated to the length the address and returns it.
52  
53 =head2 sockaddr_in
54  
55 C<static method sockaddr_in : L<Sys::Socket::Sockaddr::In|SPVM::Sys::Socket::Sockaddr::In> ($port : int, $in_addr : L<Sys::Socket::In_addr|SPVM::Sys::Socket::In_addr>);>
56  
57 Creates a new L<Sys::Socket::Sockaddr::In|SPVM::Sys::Socket::Sockaddr::In> object given the port $port and the address $in_addr, and returns it.
58  
59 The address family is set to C<AF_INET>.
60  
61 Exceptions:
62  
63 $in_addr must be defined. Otherwise an exception is thrown.
64  
65 =head2 sockaddr_in6
66  
67 C<static method sockaddr_in6 : L<Sys::Socket::Sockaddr::In6|SPVM::Sys::Socket::Sockaddr::In6> ($port : int, $in6_addr : L<Sys::Socket::In6_addr|SPVM::Sys::Socket::In6_addr>);>
68  
69 Creates a new L<Sys::Socket::Sockaddr::In6|SPVM::Sys::Socket::Sockaddr::In6> object given the port $port and the address $in_addr, and returns it.
70  
71 The address family is set to C<AF_INET6>.
72  
73 Exceptions:
74  
75 $in6_addr must be defined. Otherwise an exception is thrown.
76  
77 =head2 sockaddr_un
78  
79 C<static method sockaddr_un : L<Sys::Socket::Sockaddr::Un|SPVM::Sys::Socket::Sockaddr::Un> ($path : string);>
80  
81 Creates a new L<Sys::Socket::Sockaddr::Un|SPVM::Sys::Socket::Sockaddr::Un> object given the path $path, and returns it.
82  
83 The address family is set to C<AF_UNIX>.
84  
85 Exceptions:
86  
87 $path must be defined. Otherwise an exception is thrown.
88  
89 =head2 set_tcp_keepalive
90  
91 C<static method set_tcp_keepalive : void ($socket_fd : int, $onoff : int, $keepidle_sec : int, $keepintvl_sec : int = -1);>
92  
93 Sets the TCP keep-alive settings (C<SO_KEEPALIVE>, C<TCP_KEEPIDLE>/C<TCP_KEEPALIVE>, and C<TCP_KEEPINTVL>) in a portable way.
94  
95 Parameters:
96  
97 =over 2
98  
99 =item * C<$socket_fd> : The socket file descriptor.
100  
101 =item * C<$onoff> : Set to 1 to enable TCP keep-alive, or 0 to disable it.
102  
103 =item * C<$keepidle_sec> : The time (in seconds) the connection remains idle before TCP starts sending keep-alive probes.
104  
105 =item * C<$keepintvl_sec> : The time (in seconds) between individual keep-alive probes. If this value is negative (default is -1), C<$keepidle_sec> is used for this value for maximum portability.
106  
107 =back
108  
109 Notes:
110  
111 This method ensures consistent keep-alive behavior across different platforms. When C<$keepintvl_sec> is not specified, it applies the same duration (C<$keepidle_sec>) to both the initial idle time and the retransmission interval.
112  
113 On Windows, this method calls L<Sys::Socket#win_set_tcp_keepalive|SPVM::Sys::Socket/"win_set_tcp_keepalive"> via C<WSAIoctl> with the C<SIO_KEEPALIVE_VALS> control code. The time values are converted to milliseconds.
114  
115 On macOS, it uses the C<TCP_KEEPALIVE> constant for the idle time, while on other systems like Linux, it uses C<TCP_KEEPIDLE>. It also sets C<TCP_KEEPINTVL> and C<SO_KEEPALIVE> via L<Sys#setsockopt|SPVM::Sys/"setsockopt">.
116  
117 Note that Windows does not support retrieving these time settings via C<getsockopt>, and the number of retries (C<TCP_KEEPCNT>) is fixed by the system (typically 10 on Windows).
118  
119 See also L<Sys::Socket#win_set_tcp_keepalive|SPVM::Sys::Socket/"win_set_tcp_keepalive">.
120  
121 =head2 set_blocking
122  
123 C<static method set_blocking : void ($fd : int, $blocking : int);>
124  
125 Sets the socket file descriptor $fd to blocking or non-blocking mode in a portable way.
126  
127 Arguments:
128  
129 =over 2
130  
131 =item * C<$fd> : The socket file descriptor.
132  
133 =item * C<$blocking> : Set to a non-zero value to enable blocking mode, or 0 to enable non-blocking mode.
134  
135 =back
136  
137 =head2 inet_socketpair
138  
139 C<static method inet_socketpair : void ($socket_fd1_ref : int*, $socket_fd2_ref : int*, $domain : int, $type : int, $protocol : int);>
140  
141 Creates a pair of connected internet sockets (client and server-accepted sockets) using the loopback address (C<127.0.0.1> for C<AF_INET> or C<::1> for C<AF_INET6>).
142  
143 Parameters:
144  
145 =over 2
146  
147 =item * C<$socket_fd1_ref> : Reference to the integer where the first socket file descriptor will be stored.
148  
149 =item * C<$socket_fd2_ref> : Reference to the integer where the second socket file descriptor will be stored.
150  
151 =item * C<$domain> : The communication domain (e.g., C<AF_INET> or C<AF_INET6>).
152  
153 =item * C<$type> : The communication type (e.g., C<SOCK_STREAM>).
154  
155 =item * C<$protocol> : The particular protocol to be used with the socket.
156  
157 =back
158  
159 Notes:
160  
161 This method provides a portable way to create connected socket pairs over the network loopback interface, which is particularly useful on platforms or environments where standard L<socketpair(2)> with UNIX domain sockets is restricted or unavailable.
162  
163 It internally creates two sockets, binds the server side to a temporary port on C<127.0.0.1> (or C<::1> when C<AF_INET6> is specified), listens for connections, connects the client side to it, accepts the connection, and then closes the listening server socket.
164  
165 =head1 See Also
166  
167 =over 2
168  
169 =item * L<Sys|SPVM::Sys>
170  
171 =back
172  
173 =head1 Copyright & License
174  
175 Copyright (c) 2023 Yuki Kimoto
176  
177 MIT License
178