vendor/rustix/src/net/socket.rs

   1 use crate::fd::OwnedFd;
   2 use crate::net::{SocketAddr, SocketAddrAny, SocketAddrV4, SocketAddrV6};
   3 use crate::{backend, io};
   4 use backend::fd::{AsFd, BorrowedFd};
   5
   6 #[cfg(unix)]
   7 pub use backend::net::addr::SocketAddrUnix;
   8 pub use backend::net::types::{
   9     AcceptFlags, AddressFamily, Protocol, Shutdown, SocketFlags, SocketType,
  10 };
  11
  12 impl Default for Protocol {
  13     #[inline]
  14     fn default() -> Self {
  15         Self::IP
  16     }
  17 }
  18
  19 /// `socket(domain, type_, protocol)`—Creates a socket.
  20 ///
  21 /// POSIX guarantees that `socket` will use the lowest unused file descriptor,
  22 /// however it is not safe in general to rely on this, as file descriptors
  23 /// may be unexpectedly allocated on other threads or in libraries.
  24 ///
  25 /// # References
  26 ///  - [POSIX]
  27 ///  - [Linux]
  28 ///  - [Apple]
  29 ///  - [Winsock2]
  30 ///
  31 /// [POSIX]: https://pubs.opengroup.org/onlinepubs/9699919799/functions/socket.html
  32 /// [Linux]: https://man7.org/linux/man-pages/man2/socket.2.html
  33 /// [Apple]: https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man2/socket.2.html
  34 /// [Winsock2]: https://docs.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-socket
  35 #[inline]
  36 pub fn socket(domain: AddressFamily, type_: SocketType, protocol: Protocol) -> io::Result<OwnedFd> {
  37     backend::net::syscalls::socket(domain, type_, protocol)
  38 }
  39
  40 /// `socket_with(domain, type_ | flags, protocol)`—Creates a socket, with
  41 /// flags.
  42 ///
  43 /// POSIX guarantees that `socket` will use the lowest unused file descriptor,
  44 /// however it is not safe in general to rely on this, as file descriptors
  45 /// may be unexpectedly allocated on other threads or in libraries.
  46 ///
  47 /// `socket_with` is the same as [`socket`] but adds an additional flags
  48 /// operand.
  49 ///
  50 /// # References
  51 ///  - [POSIX]
  52 ///  - [Linux]
  53 ///  - [Apple]
  54 ///  - [Winsock2]
  55 ///
  56 /// [POSIX]: https://pubs.opengroup.org/onlinepubs/9699919799/functions/socket.html
  57 /// [Linux]: https://man7.org/linux/man-pages/man2/socket.2.html
  58 /// [Apple]: https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man2/socket.2.html
  59 /// [Winsock2]: https://docs.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-socket
  60 #[inline]
  61 pub fn socket_with(
  62     domain: AddressFamily,
  63     type_: SocketType,
  64     flags: SocketFlags,
  65     protocol: Protocol,
  66 ) -> io::Result<OwnedFd> {
  67     backend::net::syscalls::socket_with(domain, type_, flags, protocol)
  68 }
  69
  70 /// `bind(sockfd, addr)`—Binds a socket to an IP address.
  71 ///
  72 /// # References
  73 ///  - [POSIX]
  74 ///  - [Linux]
  75 ///  - [Apple]
  76 ///  - [Winsock2]
  77 ///
  78 /// [POSIX]: https://pubs.opengroup.org/onlinepubs/9699919799/functions/bind.html
  79 /// [Linux]: https://man7.org/linux/man-pages/man2/bind.2.html
  80 /// [Apple]: https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man2/bind.2.html
  81 /// [Winsock2]: https://docs.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-bind
  82 pub fn bind<Fd: AsFd>(sockfd: Fd, addr: &SocketAddr) -> io::Result<()> {
  83     _bind(sockfd.as_fd(), addr)
  84 }
  85
  86 fn _bind(sockfd: BorrowedFd<'_>, addr: &SocketAddr) -> io::Result<()> {
  87     match addr {
  88         SocketAddr::V4(v4) => backend::net::syscalls::bind_v4(sockfd, v4),
  89         SocketAddr::V6(v6) => backend::net::syscalls::bind_v6(sockfd, v6),
  90     }
  91 }
  92
  93 /// `bind(sockfd, addr)`—Binds a socket to an address.
  94 ///
  95 /// # References
  96 ///  - [POSIX]
  97 ///  - [Linux]
  98 ///  - [Apple]
  99 ///  - [Winsock2]
 100 ///
 101 /// [POSIX]: https://pubs.opengroup.org/onlinepubs/9699919799/functions/bind.html
 102 /// [Linux]: https://man7.org/linux/man-pages/man2/bind.2.html
 103 /// [Apple]: https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man2/bind.2.html
 104 /// [Winsock2]: https://docs.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-bind
 105 #[doc(alias = "bind")]
 106 pub fn bind_any<Fd: AsFd>(sockfd: Fd, addr: &SocketAddrAny) -> io::Result<()> {
 107     _bind_any(sockfd.as_fd(), addr)
 108 }
 109
 110 fn _bind_any(sockfd: BorrowedFd<'_>, addr: &SocketAddrAny) -> io::Result<()> {
 111     match addr {
 112         SocketAddrAny::V4(v4) => backend::net::syscalls::bind_v4(sockfd, v4),
 113         SocketAddrAny::V6(v6) => backend::net::syscalls::bind_v6(sockfd, v6),
 114         #[cfg(unix)]
 115         SocketAddrAny::Unix(unix) => backend::net::syscalls::bind_unix(sockfd, unix),
 116     }
 117 }
 118
 119 /// `bind(sockfd, addr, sizeof(struct sockaddr_in))`—Binds a socket to an
 120 /// IPv4 address.
 121 ///
 122 /// # References
 123 ///  - [POSIX]
 124 ///  - [Linux]
 125 ///  - [Apple]
 126 ///  - [Winsock2]
 127 ///
 128 /// [POSIX]: https://pubs.opengroup.org/onlinepubs/9699919799/functions/bind.html
 129 /// [Linux]: https://man7.org/linux/man-pages/man2/bind.2.html
 130 /// [Apple]: https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man2/bind.2.html
 131 /// [Winsock2]: https://docs.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-bind
 132 #[inline]
 133 #[doc(alias = "bind")]
 134 pub fn bind_v4<Fd: AsFd>(sockfd: Fd, addr: &SocketAddrV4) -> io::Result<()> {
 135     backend::net::syscalls::bind_v4(sockfd.as_fd(), addr)
 136 }
 137
 138 /// `bind(sockfd, addr, sizeof(struct sockaddr_in6))`—Binds a socket to an
 139 /// IPv6 address.
 140 ///
 141 /// # References
 142 ///  - [POSIX]
 143 ///  - [Linux]
 144 ///  - [Apple]
 145 ///  - [Winsock2]
 146 ///
 147 /// [POSIX]: https://pubs.opengroup.org/onlinepubs/9699919799/functions/bind.html
 148 /// [Linux]: https://man7.org/linux/man-pages/man2/bind.2.html
 149 /// [Apple]: https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man2/bind.2.html
 150 /// [Winsock2]: https://docs.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-bind
 151 #[inline]
 152 #[doc(alias = "bind")]
 153 pub fn bind_v6<Fd: AsFd>(sockfd: Fd, addr: &SocketAddrV6) -> io::Result<()> {
 154     backend::net::syscalls::bind_v6(sockfd.as_fd(), addr)
 155 }
 156
 157 /// `bind(sockfd, addr, sizeof(struct sockaddr_un))`—Binds a socket to a
 158 /// Unix-domain address.
 159 ///
 160 /// # References
 161 ///  - [POSIX]
 162 ///  - [Linux]
 163 ///  - [Apple]
 164 ///  - [Winsock2]
 165 ///
 166 /// [POSIX]: https://pubs.opengroup.org/onlinepubs/9699919799/functions/bind.html
 167 /// [Linux]: https://man7.org/linux/man-pages/man2/bind.2.html
 168 /// [Apple]: https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man2/bind.2.html
 169 /// [Winsock2]: https://docs.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-bind
 170 #[cfg(unix)]
 171 #[inline]
 172 #[doc(alias = "bind")]
 173 pub fn bind_unix<Fd: AsFd>(sockfd: Fd, addr: &SocketAddrUnix) -> io::Result<()> {
 174     backend::net::syscalls::bind_unix(sockfd.as_fd(), addr)
 175 }
 176
 177 /// `connect(sockfd, addr)`—Initiates a connection to an IP address.
 178 ///
 179 /// # References
 180 ///  - [POSIX]
 181 ///  - [Linux]
 182 ///  - [Apple]
 183 ///  - [Winsock2]
 184 ///
 185 /// [POSIX]: https://pubs.opengroup.org/onlinepubs/9699919799/functions/connect.html
 186 /// [Linux]: https://man7.org/linux/man-pages/man2/connect.2.html
 187 /// [Apple]: https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man2/connect.2.html
 188 /// [Winsock2]: https://docs.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-connect
 189 pub fn connect<Fd: AsFd>(sockfd: Fd, addr: &SocketAddr) -> io::Result<()> {
 190     _connect(sockfd.as_fd(), addr)
 191 }
 192
 193 fn _connect(sockfd: BorrowedFd<'_>, addr: &SocketAddr) -> io::Result<()> {
 194     match addr {
 195         SocketAddr::V4(v4) => backend::net::syscalls::connect_v4(sockfd, v4),
 196         SocketAddr::V6(v6) => backend::net::syscalls::connect_v6(sockfd, v6),
 197     }
 198 }
 199
 200 /// `connect(sockfd, addr)`—Initiates a connection.
 201 ///
 202 /// # References
 203 ///  - [POSIX]
 204 ///  - [Linux]
 205 ///  - [Apple]
 206 ///  - [Winsock2]
 207 ///
 208 /// [POSIX]: https://pubs.opengroup.org/onlinepubs/9699919799/functions/connect.html
 209 /// [Linux]: https://man7.org/linux/man-pages/man2/connect.2.html
 210 /// [Apple]: https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man2/connect.2.html
 211 /// [Winsock2]: https://docs.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-connect
 212 #[doc(alias = "connect")]
 213 pub fn connect_any<Fd: AsFd>(sockfd: Fd, addr: &SocketAddrAny) -> io::Result<()> {
 214     _connect_any(sockfd.as_fd(), addr)
 215 }
 216
 217 fn _connect_any(sockfd: BorrowedFd<'_>, addr: &SocketAddrAny) -> io::Result<()> {
 218     match addr {
 219         SocketAddrAny::V4(v4) => backend::net::syscalls::connect_v4(sockfd, v4),
 220         SocketAddrAny::V6(v6) => backend::net::syscalls::connect_v6(sockfd, v6),
 221         #[cfg(unix)]
 222         SocketAddrAny::Unix(unix) => backend::net::syscalls::connect_unix(sockfd, unix),
 223     }
 224 }
 225
 226 /// `connect(sockfd, addr, sizeof(struct sockaddr_in))`—Initiates a
 227 /// connection to an IPv4 address.
 228 ///
 229 /// # References
 230 ///  - [POSIX]
 231 ///  - [Linux]
 232 ///  - [Apple]
 233 ///  - [Winsock2]
 234 ///
 235 /// [POSIX]: https://pubs.opengroup.org/onlinepubs/9699919799/functions/connect.html
 236 /// [Linux]: https://man7.org/linux/man-pages/man2/connect.2.html
 237 /// [Apple]: https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man2/connect.2.html
 238 /// [Winsock2]: https://docs.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-connect
 239 #[inline]
 240 #[doc(alias = "connect")]
 241 pub fn connect_v4<Fd: AsFd>(sockfd: Fd, addr: &SocketAddrV4) -> io::Result<()> {
 242     backend::net::syscalls::connect_v4(sockfd.as_fd(), addr)
 243 }
 244
 245 /// `connect(sockfd, addr, sizeof(struct sockaddr_in6))`—Initiates a
 246 /// connection to an IPv6 address.
 247 ///
 248 /// # References
 249 ///  - [POSIX]
 250 ///  - [Linux]
 251 ///  - [Apple]
 252 ///  - [Winsock2]
 253 ///
 254 /// [POSIX]: https://pubs.opengroup.org/onlinepubs/9699919799/functions/connect.html
 255 /// [Linux]: https://man7.org/linux/man-pages/man2/connect.2.html
 256 /// [Apple]: https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man2/connect.2.html
 257 /// [Winsock2]: https://docs.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-connect
 258 #[inline]
 259 #[doc(alias = "connect")]
 260 pub fn connect_v6<Fd: AsFd>(sockfd: Fd, addr: &SocketAddrV6) -> io::Result<()> {
 261     backend::net::syscalls::connect_v6(sockfd.as_fd(), addr)
 262 }
 263
 264 /// `connect(sockfd, addr, sizeof(struct sockaddr_un))`—Initiates a
 265 /// connection to a Unix-domain address.
 266 ///
 267 /// # References
 268 ///  - [POSIX]
 269 ///  - [Linux]
 270 ///  - [Apple]
 271 ///  - [Winsock2]
 272 ///
 273 /// [POSIX]: https://pubs.opengroup.org/onlinepubs/9699919799/functions/connect.html
 274 /// [Linux]: https://man7.org/linux/man-pages/man2/connect.2.html
 275 /// [Apple]: https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man2/connect.2.html
 276 /// [Winsock2]: https://docs.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-connect
 277 #[cfg(unix)]
 278 #[inline]
 279 #[doc(alias = "connect")]
 280 pub fn connect_unix<Fd: AsFd>(sockfd: Fd, addr: &SocketAddrUnix) -> io::Result<()> {
 281     backend::net::syscalls::connect_unix(sockfd.as_fd(), addr)
 282 }
 283
 284 /// `listen(fd, backlog)`—Enables listening for incoming connections.
 285 ///
 286 /// # References
 287 ///  - [POSIX]
 288 ///  - [Linux]
 289 ///  - [Apple]
 290 ///  - [Winsock2]
 291 ///
 292 /// [POSIX]: https://pubs.opengroup.org/onlinepubs/9699919799/functions/listen.html
 293 /// [Linux]: https://man7.org/linux/man-pages/man2/listen.2.html
 294 /// [Apple]: https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man2/listen.2.html
 295 /// [Winsock2]: https://docs.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-listen
 296 #[inline]
 297 pub fn listen<Fd: AsFd>(sockfd: Fd, backlog: i32) -> io::Result<()> {
 298     backend::net::syscalls::listen(sockfd.as_fd(), backlog)
 299 }
 300
 301 /// `accept(fd, NULL, NULL)`—Accepts an incoming connection.
 302 ///
 303 /// Use [`acceptfrom`] to retrieve the peer address.
 304 ///
 305 /// POSIX guarantees that `accept` will use the lowest unused file descriptor,
 306 /// however it is not safe in general to rely on this, as file descriptors may
 307 /// be unexpectedly allocated on other threads or in libraries.
 308 ///
 309 /// # References
 310 ///  - [POSIX]
 311 ///  - [Linux]
 312 ///  - [Apple]
 313 ///  - [Winsock2]
 314 ///
 315 /// [POSIX]: https://pubs.opengroup.org/onlinepubs/9699919799/functions/accept.html
 316 /// [Linux]: https://man7.org/linux/man-pages/man2/accept.2.html
 317 /// [Apple]: https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man2/accept.2.html
 318 /// [Winsock2]: https://docs.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-accept
 319 #[inline]
 320 #[doc(alias = "accept4")]
 321 pub fn accept<Fd: AsFd>(sockfd: Fd) -> io::Result<OwnedFd> {
 322     backend::net::syscalls::accept(sockfd.as_fd())
 323 }
 324
 325 /// `accept4(fd, NULL, NULL, flags)`—Accepts an incoming connection, with
 326 /// flags.
 327 ///
 328 /// Use [`acceptfrom_with`] to retrieve the peer address.
 329 ///
 330 /// Even though POSIX guarantees that this will use the lowest unused file
 331 /// descriptor, it is not safe in general to rely on this, as file descriptors
 332 /// may be unexpectedly allocated on other threads or in libraries.
 333 ///
 334 /// `accept_with` is the same as [`accept`] but adds an additional flags
 335 /// operand.
 336 ///
 337 /// # References
 338 ///  - [Linux]
 339 ///
 340 /// [Linux]: https://man7.org/linux/man-pages/man2/accept4.2.html
 341 #[inline]
 342 #[doc(alias = "accept4")]
 343 pub fn accept_with<Fd: AsFd>(sockfd: Fd, flags: AcceptFlags) -> io::Result<OwnedFd> {
 344     backend::net::syscalls::accept_with(sockfd.as_fd(), flags)
 345 }
 346
 347 /// `accept(fd, &addr, &len)`—Accepts an incoming connection and returns the
 348 /// peer address.
 349 ///
 350 /// Use [`accept`] if the peer address isn't needed.
 351 ///
 352 /// # References
 353 ///  - [POSIX]
 354 ///  - [Linux]
 355 ///  - [Apple]
 356 ///  - [Winsock2]
 357 ///
 358 /// [POSIX]: https://pubs.opengroup.org/onlinepubs/9699919799/functions/accept.html
 359 /// [Linux]: https://man7.org/linux/man-pages/man2/accept.2.html
 360 /// [Apple]: https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man2/accept.2.html
 361 /// [Winsock2]: https://docs.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-accept
 362 #[inline]
 363 #[doc(alias = "accept4")]
 364 pub fn acceptfrom<Fd: AsFd>(sockfd: Fd) -> io::Result<(OwnedFd, Option<SocketAddrAny>)> {
 365     backend::net::syscalls::acceptfrom(sockfd.as_fd())
 366 }
 367
 368 /// `accept4(fd, &addr, &len, flags)`—Accepts an incoming connection and
 369 /// returns the peer address, with flags.
 370 ///
 371 /// Use [`accept_with`] if the peer address isn't needed.
 372 ///
 373 /// `acceptfrom_with` is the same as [`acceptfrom`] but adds an additional
 374 /// flags operand.
 375 ///
 376 /// # References
 377 ///  - [Linux]
 378 ///
 379 /// [Linux]: https://man7.org/linux/man-pages/man2/accept4.2.html
 380 #[inline]
 381 #[doc(alias = "accept4")]
 382 pub fn acceptfrom_with<Fd: AsFd>(
 383     sockfd: Fd,
 384     flags: AcceptFlags,
 385 ) -> io::Result<(OwnedFd, Option<SocketAddrAny>)> {
 386     backend::net::syscalls::acceptfrom_with(sockfd.as_fd(), flags)
 387 }
 388
 389 /// `shutdown(fd, how)`—Closes the read and/or write sides of a stream.
 390 ///
 391 /// # References
 392 ///  - [POSIX]
 393 ///  - [Linux]
 394 ///  - [Apple]
 395 ///  - [Winsock2]
 396 ///
 397 /// [POSIX]: https://pubs.opengroup.org/onlinepubs/9699919799/functions/shutdown.html
 398 /// [Linux]: https://man7.org/linux/man-pages/man2/shutdown.2.html
 399 /// [Apple]: https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man2/shutdown.2.html
 400 /// [Winsock2]: https://docs.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-shutdown
 401 #[inline]
 402 pub fn shutdown<Fd: AsFd>(sockfd: Fd, how: Shutdown) -> io::Result<()> {
 403     backend::net::syscalls::shutdown(sockfd.as_fd(), how)
 404 }
 405
 406 /// `getsockname(fd, addr, len)`—Returns the address a socket is bound to.
 407 ///
 408 /// # References
 409 ///  - [POSIX]
 410 ///  - [Linux]
 411 ///  - [Apple]
 412 ///  - [Winsock2]
 413 ///
 414 /// [POSIX]: https://pubs.opengroup.org/onlinepubs/9699919799/functions/getsockname.html
 415 /// [Linux]: https://man7.org/linux/man-pages/man2/getsockname.2.html
 416 /// [Apple]: https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man2/getsockname.2.html
 417 /// [Winsock2]: https://docs.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-getsockname
 418 #[inline]
 419 pub fn getsockname<Fd: AsFd>(sockfd: Fd) -> io::Result<SocketAddrAny> {
 420     backend::net::syscalls::getsockname(sockfd.as_fd())
 421 }
 422
 423 /// `getpeername(fd, addr, len)`—Returns the address a socket is connected
 424 /// to.
 425 ///
 426 /// # References
 427 ///  - [POSIX]
 428 ///  - [Linux]
 429 ///  - [Apple]
 430 ///  - [Winsock2]
 431 ///
 432 /// [POSIX]: https://pubs.opengroup.org/onlinepubs/9699919799/functions/getpeername.html
 433 /// [Linux]: https://man7.org/linux/man-pages/man2/getpeername.2.html
 434 /// [Apple]: https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man2/getpeername.2.html
 435 /// [Winsock2]: https://docs.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-getpeername
 436 #[inline]
 437 pub fn getpeername<Fd: AsFd>(sockfd: Fd) -> io::Result<Option<SocketAddrAny>> {
 438     backend::net::syscalls::getpeername(sockfd.as_fd())
 439 }