| 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 |