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