Debian Codegraph @

.cargo/vendor/rustix/src/net/socket.rs

raw
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(target_os = "linux")]
7 use crate::net::xdp::SocketAddrXdp;
8 pub use crate::net::{AddressFamily, Protocol, Shutdown, SocketFlags, SocketType};
9 #[cfg(unix)]
10 pub use backend::net::addr::SocketAddrUnix;
11
12 /// `socket(domain, type_, protocol)`—Creates a socket.
13 ///
14 /// POSIX guarantees that `socket` will use the lowest unused file descriptor,
15 /// however it is not safe in general to rely on this, as file descriptors may
16 /// be unexpectedly allocated on other threads or in libraries.
17 ///
18 /// To pass extra flags such as [`SocketFlags::CLOEXEC`] or
19 /// [`SocketFlags::NONBLOCK`], use [`socket_with`].
20 ///
21 /// # References
22 /// - [Beej's Guide to Network Programming]
23 /// - [POSIX]
24 /// - [Linux]
25 /// - [Apple]
26 /// - [Winsock]
27 /// - [FreeBSD]
28 /// - [NetBSD]
29 /// - [OpenBSD]
30 /// - [DragonFly BSD]
31 /// - [illumos]
32 /// - [glibc]
33 ///
34 /// [Beej's Guide to Network Programming]: https://beej.us/guide/bgnet/html/split/system-calls-or-bust.html#socket
35 /// [POSIX]: https://pubs.opengroup.org/onlinepubs/9699919799/functions/socket.html
36 /// [Linux]: https://man7.org/linux/man-pages/man2/socket.2.html
37 /// [Apple]: https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man2/socket.2.html
38 /// [Winsock]: https://docs.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-socket
39 /// [FreeBSD]: https://man.freebsd.org/cgi/man.cgi?query=socket&sektion=2
40 /// [NetBSD]: https://man.netbsd.org/socket.2
41 /// [OpenBSD]: https://man.openbsd.org/socket.2
42 /// [DragonFly BSD]: https://man.dragonflybsd.org/?command=socket&section=2
43 /// [illumos]: https://illumos.org/man/3SOCKET/socket
44 /// [glibc]: https://www.gnu.org/software/libc/manual/html_node/Creating-a-Socket.html
45 #[inline]
46 pub fn socket(
47 domain: AddressFamily,
48 type_: SocketType,
49 protocol: Option<Protocol>,
50 ) -> io::Result<OwnedFd> {
51 backend::net::syscalls::socket(domain, type_, protocol)
52 }
53
54 /// `socket_with(domain, type_ | flags, protocol)`—Creates a socket, with
55 /// flags.
56 ///
57 /// POSIX guarantees that `socket` will use the lowest unused file descriptor,
58 /// however it is not safe in general to rely on this, as file descriptors may
59 /// be unexpectedly allocated on other threads or in libraries.
60 ///
61 /// `socket_with` is the same as [`socket`] but adds an additional flags
62 /// operand.
63 ///
64 /// # References
65 /// - [Beej's Guide to Network Programming]
66 /// - [POSIX]
67 /// - [Linux]
68 /// - [Apple]
69 /// - [Winsock]
70 /// - [FreeBSD]
71 /// - [NetBSD]
72 /// - [OpenBSD]
73 /// - [DragonFly BSD]
74 /// - [illumos]
75 /// - [glibc]
76 ///
77 /// [Beej's Guide to Network Programming]: https://beej.us/guide/bgnet/html/split/system-calls-or-bust.html#socket
78 /// [POSIX]: https://pubs.opengroup.org/onlinepubs/9699919799/functions/socket.html
79 /// [Linux]: https://man7.org/linux/man-pages/man2/socket.2.html
80 /// [Apple]: https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man2/socket.2.html
81 /// [Winsock]: https://docs.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-socket
82 /// [FreeBSD]: https://man.freebsd.org/cgi/man.cgi?query=socket&sektion=2
83 /// [NetBSD]: https://man.netbsd.org/socket.2
84 /// [OpenBSD]: https://man.openbsd.org/socket.2
85 /// [DragonFly BSD]: https://man.dragonflybsd.org/?command=socket&section=2
86 /// [illumos]: https://illumos.org/man/3SOCKET/socket
87 /// [glibc]: https://www.gnu.org/software/libc/manual/html_node/Creating-a-Socket.html
88 #[doc(alias("socket"))]
89 #[inline]
90 pub fn socket_with(
91 domain: AddressFamily,
92 type_: SocketType,
93 flags: SocketFlags,
94 protocol: Option<Protocol>,
95 ) -> io::Result<OwnedFd> {
96 backend::net::syscalls::socket_with(domain, type_, flags, protocol)
97 }
98
99 /// `bind(sockfd, addr)`—Binds a socket to an IP address.
100 ///
101 /// # References
102 /// - [Beej's Guide to Network Programming]
103 /// - [POSIX]
104 /// - [Linux]
105 /// - [Apple]
106 /// - [Winsock]
107 /// - [FreeBSD]
108 /// - [NetBSD]
109 /// - [OpenBSD]
110 /// - [DragonFly BSD]
111 /// - [illumos]
112 /// - [glibc]
113 ///
114 /// [Beej's Guide to Network Programming]: https://beej.us/guide/bgnet/html/split/system-calls-or-bust.html#bind
115 /// [POSIX]: https://pubs.opengroup.org/onlinepubs/9699919799/functions/bind.html
116 /// [Linux]: https://man7.org/linux/man-pages/man2/bind.2.html
117 /// [Apple]: https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man2/bind.2.html
118 /// [Winsock]: https://docs.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-bind
119 /// [FreeBSD]: https://man.freebsd.org/cgi/man.cgi?query=bind&sektion=2
120 /// [NetBSD]: https://man.netbsd.org/bind.2
121 /// [OpenBSD]: https://man.openbsd.org/bind.2
122 /// [DragonFly BSD]: https://man.dragonflybsd.org/?command=bind&section=2
123 /// [illumos]: https://illumos.org/man/3SOCKET/bind
124 /// [glibc]: https://www.gnu.org/software/libc/manual/html_node/Setting-Address.html
125 pub fn bind<Fd: AsFd>(sockfd: Fd, addr: &SocketAddr) -> io::Result<()> {
126 _bind(sockfd.as_fd(), addr)
127 }
128
129 fn _bind(sockfd: BorrowedFd<'_>, addr: &SocketAddr) -> io::Result<()> {
130 match addr {
131 SocketAddr::V4(v4) => backend::net::syscalls::bind_v4(sockfd, v4),
132 SocketAddr::V6(v6) => backend::net::syscalls::bind_v6(sockfd, v6),
133 }
134 }
135
136 /// `bind(sockfd, addr)`—Binds a socket to an address.
137 ///
138 /// # References
139 /// - [Beej's Guide to Network Programming]
140 /// - [POSIX]
141 /// - [Linux]
142 /// - [Apple]
143 /// - [Winsock]
144 /// - [FreeBSD]
145 /// - [NetBSD]
146 /// - [OpenBSD]
147 /// - [DragonFly BSD]
148 /// - [illumos]
149 /// - [glibc]
150 ///
151 /// [Beej's Guide to Network Programming]: https://beej.us/guide/bgnet/html/split/system-calls-or-bust.html#bind
152 /// [POSIX]: https://pubs.opengroup.org/onlinepubs/9699919799/functions/bind.html
153 /// [Linux]: https://man7.org/linux/man-pages/man2/bind.2.html
154 /// [Apple]: https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man2/bind.2.html
155 /// [Winsock]: https://docs.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-bind
156 /// [FreeBSD]: https://man.freebsd.org/cgi/man.cgi?query=bind&sektion=2
157 /// [NetBSD]: https://man.netbsd.org/bind.2
158 /// [OpenBSD]: https://man.openbsd.org/bind.2
159 /// [DragonFly BSD]: https://man.dragonflybsd.org/?command=bind&section=2
160 /// [illumos]: https://illumos.org/man/3SOCKET/bind
161 /// [glibc]: https://www.gnu.org/software/libc/manual/html_node/Setting-Address.html
162 #[doc(alias = "bind")]
163 pub fn bind_any<Fd: AsFd>(sockfd: Fd, addr: &SocketAddrAny) -> io::Result<()> {
164 _bind_any(sockfd.as_fd(), addr)
165 }
166
167 fn _bind_any(sockfd: BorrowedFd<'_>, addr: &SocketAddrAny) -> io::Result<()> {
168 match addr {
169 SocketAddrAny::V4(v4) => backend::net::syscalls::bind_v4(sockfd, v4),
170 SocketAddrAny::V6(v6) => backend::net::syscalls::bind_v6(sockfd, v6),
171 #[cfg(unix)]
172 SocketAddrAny::Unix(unix) => backend::net::syscalls::bind_unix(sockfd, unix),
173 #[cfg(target_os = "linux")]
174 SocketAddrAny::Xdp(xdp) => backend::net::syscalls::bind_xdp(sockfd, xdp),
175 }
176 }
177
178 /// `bind(sockfd, addr, sizeof(struct sockaddr_in))`—Binds a socket to an
179 /// IPv4 address.
180 ///
181 /// # References
182 /// - [Beej's Guide to Network Programming]
183 /// - [POSIX]
184 /// - [Linux]
185 /// - [Apple]
186 /// - [Winsock]
187 /// - [FreeBSD]
188 /// - [NetBSD]
189 /// - [OpenBSD]
190 /// - [DragonFly BSD]
191 /// - [illumos]
192 /// - [glibc]
193 ///
194 /// [Beej's Guide to Network Programming]: https://beej.us/guide/bgnet/html/split/system-calls-or-bust.html#bind
195 /// [POSIX]: https://pubs.opengroup.org/onlinepubs/9699919799/functions/bind.html
196 /// [Linux]: https://man7.org/linux/man-pages/man2/bind.2.html
197 /// [Apple]: https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man2/bind.2.html
198 /// [Winsock]: https://docs.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-bind
199 /// [FreeBSD]: https://man.freebsd.org/cgi/man.cgi?query=bind&sektion=2
200 /// [NetBSD]: https://man.netbsd.org/bind.2
201 /// [OpenBSD]: https://man.openbsd.org/bind.2
202 /// [DragonFly BSD]: https://man.dragonflybsd.org/?command=bind&section=2
203 /// [illumos]: https://illumos.org/man/3SOCKET/bind
204 /// [glibc]: https://www.gnu.org/software/libc/manual/html_node/Setting-Address.html
205 #[inline]
206 #[doc(alias = "bind")]
207 pub fn bind_v4<Fd: AsFd>(sockfd: Fd, addr: &SocketAddrV4) -> io::Result<()> {
208 backend::net::syscalls::bind_v4(sockfd.as_fd(), addr)
209 }
210
211 /// `bind(sockfd, addr, sizeof(struct sockaddr_in6))`—Binds a socket to an
212 /// IPv6 address.
213 ///
214 /// # References
215 /// - [Beej's Guide to Network Programming]
216 /// - [POSIX]
217 /// - [Linux]
218 /// - [Apple]
219 /// - [Winsock]
220 /// - [FreeBSD]
221 /// - [NetBSD]
222 /// - [OpenBSD]
223 /// - [DragonFly BSD]
224 /// - [illumos]
225 /// - [glibc]
226 ///
227 /// [Beej's Guide to Network Programming]: https://beej.us/guide/bgnet/html/split/system-calls-or-bust.html#bind
228 /// [POSIX]: https://pubs.opengroup.org/onlinepubs/9699919799/functions/bind.html
229 /// [Linux]: https://man7.org/linux/man-pages/man2/bind.2.html
230 /// [Apple]: https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man2/bind.2.html
231 /// [Winsock]: https://docs.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-bind
232 /// [FreeBSD]: https://man.freebsd.org/cgi/man.cgi?query=bind&sektion=2
233 /// [NetBSD]: https://man.netbsd.org/bind.2
234 /// [OpenBSD]: https://man.openbsd.org/bind.2
235 /// [DragonFly BSD]: https://man.dragonflybsd.org/?command=bind&section=2
236 /// [illumos]: https://illumos.org/man/3SOCKET/bind
237 /// [glibc]: https://www.gnu.org/software/libc/manual/html_node/Setting-Address.html
238 #[inline]
239 #[doc(alias = "bind")]
240 pub fn bind_v6<Fd: AsFd>(sockfd: Fd, addr: &SocketAddrV6) -> io::Result<()> {
241 backend::net::syscalls::bind_v6(sockfd.as_fd(), addr)
242 }
243
244 /// `bind(sockfd, addr, sizeof(struct sockaddr_un))`—Binds a socket to a
245 /// Unix-domain address.
246 ///
247 /// # References
248 /// - [Beej's Guide to Network Programming]
249 /// - [POSIX]
250 /// - [Linux]
251 /// - [Apple]
252 /// - [Winsock]
253 /// - [FreeBSD]
254 /// - [NetBSD]
255 /// - [OpenBSD]
256 /// - [DragonFly BSD]
257 /// - [illumos]
258 /// - [glibc]
259 ///
260 /// [Beej's Guide to Network Programming]: https://beej.us/guide/bgnet/html/split/system-calls-or-bust.html#bind
261 /// [POSIX]: https://pubs.opengroup.org/onlinepubs/9699919799/functions/bind.html
262 /// [Linux]: https://man7.org/linux/man-pages/man2/bind.2.html
263 /// [Apple]: https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man2/bind.2.html
264 /// [Winsock]: https://docs.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-bind
265 /// [FreeBSD]: https://man.freebsd.org/cgi/man.cgi?query=bind&sektion=2
266 /// [NetBSD]: https://man.netbsd.org/bind.2
267 /// [OpenBSD]: https://man.openbsd.org/bind.2
268 /// [DragonFly BSD]: https://man.dragonflybsd.org/?command=bind&section=2
269 /// [illumos]: https://illumos.org/man/3SOCKET/bind
270 /// [glibc]: https://www.gnu.org/software/libc/manual/html_node/Setting-Address.html
271 #[cfg(unix)]
272 #[inline]
273 #[doc(alias = "bind")]
274 pub fn bind_unix<Fd: AsFd>(sockfd: Fd, addr: &SocketAddrUnix) -> io::Result<()> {
275 backend::net::syscalls::bind_unix(sockfd.as_fd(), addr)
276 }
277
278 /// `bind(sockfd, addr, sizeof(struct sockaddr_un))`—Binds a socket to a XDP
279 /// address.
280 ///
281 /// # References
282 /// - [Linux]
283 ///
284 /// [Linux]: https://man7.org/linux/man-pages/man2/bind.2.html
285 #[cfg(target_os = "linux")]
286 #[inline]
287 #[doc(alias = "bind")]
288 pub fn bind_xdp<Fd: AsFd>(sockfd: Fd, addr: &SocketAddrXdp) -> io::Result<()> {
289 backend::net::syscalls::bind_xdp(sockfd.as_fd(), addr)
290 }
291
292 /// `connect(sockfd, addr)`—Initiates a connection to an IP address.
293 ///
294 /// On Windows, a non-blocking socket returns [`Errno::WOULDBLOCK`] if the
295 /// connection cannot be completed immediately, rather than
296 /// `Errno::INPROGRESS`.
297 ///
298 /// # References
299 /// - [Beej's Guide to Network Programming]
300 /// - [POSIX]
301 /// - [Linux]
302 /// - [Apple]
303 /// - [Winsock]
304 /// - [FreeBSD]
305 /// - [NetBSD]
306 /// - [OpenBSD]
307 /// - [DragonFly BSD]
308 /// - [illumos]
309 /// - [glibc]
310 ///
311 /// [Beej's Guide to Network Programming]: https://beej.us/guide/bgnet/html/split/system-calls-or-bust.html#connect
312 /// [POSIX]: https://pubs.opengroup.org/onlinepubs/9699919799/functions/connect.html
313 /// [Linux]: https://man7.org/linux/man-pages/man2/connect.2.html
314 /// [Apple]: https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man2/connect.2.html
315 /// [Winsock]: https://docs.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-connect
316 /// [FreeBSD]: https://man.freebsd.org/cgi/man.cgi?query=connect&sektion=2
317 /// [NetBSD]: https://man.netbsd.org/connect.2
318 /// [OpenBSD]: https://man.openbsd.org/connect.2
319 /// [DragonFly BSD]: https://man.dragonflybsd.org/?command=connect&section=2
320 /// [illumos]: https://illumos.org/man/3SOCKET/connect
321 /// [glibc]: https://www.gnu.org/software/libc/manual/html_node/Connecting.html
322 /// [`Errno::WOULDBLOCK`]: io::Errno::WOULDBLOCK
323 pub fn connect<Fd: AsFd>(sockfd: Fd, addr: &SocketAddr) -> io::Result<()> {
324 _connect(sockfd.as_fd(), addr)
325 }
326
327 fn _connect(sockfd: BorrowedFd<'_>, addr: &SocketAddr) -> io::Result<()> {
328 match addr {
329 SocketAddr::V4(v4) => backend::net::syscalls::connect_v4(sockfd, v4),
330 SocketAddr::V6(v6) => backend::net::syscalls::connect_v6(sockfd, v6),
331 }
332 }
333
334 /// `connect(sockfd, addr)`—Initiates a connection.
335 ///
336 /// # References
337 /// - [Beej's Guide to Network Programming]
338 /// - [POSIX]
339 /// - [Linux]
340 /// - [Apple]
341 /// - [Winsock]
342 /// - [FreeBSD]
343 /// - [NetBSD]
344 /// - [OpenBSD]
345 /// - [DragonFly BSD]
346 /// - [illumos]
347 /// - [glibc]
348 ///
349 /// [Beej's Guide to Network Programming]: https://beej.us/guide/bgnet/html/split/system-calls-or-bust.html#connect
350 /// [POSIX]: https://pubs.opengroup.org/onlinepubs/9699919799/functions/connect.html
351 /// [Linux]: https://man7.org/linux/man-pages/man2/connect.2.html
352 /// [Apple]: https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man2/connect.2.html
353 /// [Winsock]: https://docs.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-connect
354 /// [FreeBSD]: https://man.freebsd.org/cgi/man.cgi?query=connect&sektion=2
355 /// [NetBSD]: https://man.netbsd.org/connect.2
356 /// [OpenBSD]: https://man.openbsd.org/connect.2
357 /// [DragonFly BSD]: https://man.dragonflybsd.org/?command=connect&section=2
358 /// [illumos]: https://illumos.org/man/3SOCKET/connect
359 /// [glibc]: https://www.gnu.org/software/libc/manual/html_node/Connecting.html
360 #[doc(alias = "connect")]
361 pub fn connect_any<Fd: AsFd>(sockfd: Fd, addr: &SocketAddrAny) -> io::Result<()> {
362 _connect_any(sockfd.as_fd(), addr)
363 }
364
365 fn _connect_any(sockfd: BorrowedFd<'_>, addr: &SocketAddrAny) -> io::Result<()> {
366 match addr {
367 SocketAddrAny::V4(v4) => backend::net::syscalls::connect_v4(sockfd, v4),
368 SocketAddrAny::V6(v6) => backend::net::syscalls::connect_v6(sockfd, v6),
369 #[cfg(unix)]
370 SocketAddrAny::Unix(unix) => backend::net::syscalls::connect_unix(sockfd, unix),
371 #[cfg(target_os = "linux")]
372 SocketAddrAny::Xdp(_) => Err(io::Errno::OPNOTSUPP),
373 }
374 }
375
376 /// `connect(sockfd, addr, sizeof(struct sockaddr_in))`—Initiates a
377 /// connection to an IPv4 address.
378 ///
379 /// # References
380 /// - [Beej's Guide to Network Programming]
381 /// - [POSIX]
382 /// - [Linux]
383 /// - [Apple]
384 /// - [Winsock]
385 /// - [FreeBSD]
386 /// - [NetBSD]
387 /// - [OpenBSD]
388 /// - [DragonFly BSD]
389 /// - [illumos]
390 /// - [glibc]
391 ///
392 /// [Beej's Guide to Network Programming]: https://beej.us/guide/bgnet/html/split/system-calls-or-bust.html#connect
393 /// [POSIX]: https://pubs.opengroup.org/onlinepubs/9699919799/functions/connect.html
394 /// [Linux]: https://man7.org/linux/man-pages/man2/connect.2.html
395 /// [Apple]: https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man2/connect.2.html
396 /// [Winsock]: https://docs.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-connect
397 /// [FreeBSD]: https://man.freebsd.org/cgi/man.cgi?query=connect&sektion=2
398 /// [NetBSD]: https://man.netbsd.org/connect.2
399 /// [OpenBSD]: https://man.openbsd.org/connect.2
400 /// [DragonFly BSD]: https://man.dragonflybsd.org/?command=connect&section=2
401 /// [illumos]: https://illumos.org/man/3SOCKET/connect
402 /// [glibc]: https://www.gnu.org/software/libc/manual/html_node/Connecting.html
403 #[inline]
404 #[doc(alias = "connect")]
405 pub fn connect_v4<Fd: AsFd>(sockfd: Fd, addr: &SocketAddrV4) -> io::Result<()> {
406 backend::net::syscalls::connect_v4(sockfd.as_fd(), addr)
407 }
408
409 /// `connect(sockfd, addr, sizeof(struct sockaddr_in6))`—Initiates a
410 /// connection to an IPv6 address.
411 ///
412 /// # References
413 /// - [Beej's Guide to Network Programming]
414 /// - [POSIX]
415 /// - [Linux]
416 /// - [Apple]
417 /// - [Winsock]
418 /// - [FreeBSD]
419 /// - [NetBSD]
420 /// - [OpenBSD]
421 /// - [DragonFly BSD]
422 /// - [illumos]
423 /// - [glibc]
424 ///
425 /// [Beej's Guide to Network Programming]: https://beej.us/guide/bgnet/html/split/system-calls-or-bust.html#connect
426 /// [POSIX]: https://pubs.opengroup.org/onlinepubs/9699919799/functions/connect.html
427 /// [Linux]: https://man7.org/linux/man-pages/man2/connect.2.html
428 /// [Apple]: https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man2/connect.2.html
429 /// [Winsock]: https://docs.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-connect
430 /// [FreeBSD]: https://man.freebsd.org/cgi/man.cgi?query=connect&sektion=2
431 /// [NetBSD]: https://man.netbsd.org/connect.2
432 /// [OpenBSD]: https://man.openbsd.org/connect.2
433 /// [DragonFly BSD]: https://man.dragonflybsd.org/?command=connect&section=2
434 /// [illumos]: https://illumos.org/man/3SOCKET/connect
435 /// [glibc]: https://www.gnu.org/software/libc/manual/html_node/Connecting.html
436 #[inline]
437 #[doc(alias = "connect")]
438 pub fn connect_v6<Fd: AsFd>(sockfd: Fd, addr: &SocketAddrV6) -> io::Result<()> {
439 backend::net::syscalls::connect_v6(sockfd.as_fd(), addr)
440 }
441
442 /// `connect(sockfd, addr, sizeof(struct sockaddr_un))`—Initiates a
443 /// connection to a Unix-domain address.
444 ///
445 /// # References
446 /// - [Beej's Guide to Network Programming]
447 /// - [POSIX]
448 /// - [Linux]
449 /// - [Apple]
450 /// - [Winsock]
451 /// - [FreeBSD]
452 /// - [NetBSD]
453 /// - [OpenBSD]
454 /// - [DragonFly BSD]
455 /// - [illumos]
456 /// - [glibc]
457 ///
458 /// [Beej's Guide to Network Programming]: https://beej.us/guide/bgnet/html/split/system-calls-or-bust.html#connect
459 /// [POSIX]: https://pubs.opengroup.org/onlinepubs/9699919799/functions/connect.html
460 /// [Linux]: https://man7.org/linux/man-pages/man2/connect.2.html
461 /// [Apple]: https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man2/connect.2.html
462 /// [Winsock]: https://docs.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-connect
463 /// [FreeBSD]: https://man.freebsd.org/cgi/man.cgi?query=connect&sektion=2
464 /// [NetBSD]: https://man.netbsd.org/connect.2
465 /// [OpenBSD]: https://man.openbsd.org/connect.2
466 /// [DragonFly BSD]: https://man.dragonflybsd.org/?command=connect&section=2
467 /// [illumos]: https://illumos.org/man/3SOCKET/connect
468 /// [glibc]: https://www.gnu.org/software/libc/manual/html_node/Connecting.html
469 #[cfg(unix)]
470 #[inline]
471 #[doc(alias = "connect")]
472 pub fn connect_unix<Fd: AsFd>(sockfd: Fd, addr: &SocketAddrUnix) -> io::Result<()> {
473 backend::net::syscalls::connect_unix(sockfd.as_fd(), addr)
474 }
475
476 /// `connect(sockfd, {.sa_family = AF_UNSPEC}, sizeof(struct sockaddr))`
477 /// — Dissolve the socket's association.
478 ///
479 /// On UDP sockets, BSD platforms report [`Errno::AFNOSUPPORT`] or
480 /// [`Errno::INVAL`] even if the disconnect was successful.
481 ///
482 /// # References
483 /// - [Beej's Guide to Network Programming]
484 /// - [POSIX]
485 /// - [Linux]
486 /// - [Apple]
487 /// - [Winsock]
488 /// - [FreeBSD]
489 /// - [NetBSD]
490 /// - [OpenBSD]
491 /// - [DragonFly BSD]
492 /// - [illumos]
493 /// - [glibc]
494 ///
495 /// [Beej's Guide to Network Programming]: https://beej.us/guide/bgnet/html/split/system-calls-or-bust.html#connect
496 /// [POSIX]: https://pubs.opengroup.org/onlinepubs/9699919799/functions/connect.html
497 /// [Linux]: https://man7.org/linux/man-pages/man2/connect.2.html
498 /// [Apple]: https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man2/connect.2.html
499 /// [Winsock]: https://docs.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-connect
500 /// [FreeBSD]: https://man.freebsd.org/cgi/man.cgi?query=connect&sektion=2
501 /// [NetBSD]: https://man.netbsd.org/connect.2
502 /// [OpenBSD]: https://man.openbsd.org/connect.2
503 /// [DragonFly BSD]: https://man.dragonflybsd.org/?command=connect&section=2
504 /// [illumos]: https://illumos.org/man/3SOCKET/connect
505 /// [glibc]: https://www.gnu.org/software/libc/manual/html_node/Connecting.html
506 /// [`Errno::AFNOSUPPORT`]: io::Errno::AFNOSUPPORT
507 /// [`Errno::INVAL`]: io::Errno::INVAL
508 #[inline]
509 #[doc(alias = "connect")]
510 pub fn connect_unspec<Fd: AsFd>(sockfd: Fd) -> io::Result<()> {
511 backend::net::syscalls::connect_unspec(sockfd.as_fd())
512 }
513
514 /// `listen(fd, backlog)`—Enables listening for incoming connections.
515 ///
516 /// # References
517 /// - [Beej's Guide to Network Programming]
518 /// - [POSIX]
519 /// - [Linux]
520 /// - [Apple]
521 /// - [Winsock]
522 /// - [FreeBSD]
523 /// - [NetBSD]
524 /// - [OpenBSD]
525 /// - [DragonFly BSD]
526 /// - [illumos]
527 /// - [glibc]
528 ///
529 /// [Beej's Guide to Network Programming]: https://beej.us/guide/bgnet/html/split/system-calls-or-bust.html#listen
530 /// [POSIX]: https://pubs.opengroup.org/onlinepubs/9699919799/functions/listen.html
531 /// [Linux]: https://man7.org/linux/man-pages/man2/listen.2.html
532 /// [Apple]: https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man2/listen.2.html
533 /// [Winsock]: https://docs.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-listen
534 /// [FreeBSD]: https://man.freebsd.org/cgi/man.cgi?query=listen&sektion=2
535 /// [NetBSD]: https://man.netbsd.org/listen.2
536 /// [OpenBSD]: https://man.openbsd.org/listen.2
537 /// [DragonFly BSD]: https://man.dragonflybsd.org/?command=listen&section=2
538 /// [illumos]: https://illumos.org/man/3SOCKET/listen
539 /// [glibc]: https://www.gnu.org/software/libc/manual/html_node/Listening.html
540 #[inline]
541 pub fn listen<Fd: AsFd>(sockfd: Fd, backlog: i32) -> io::Result<()> {
542 backend::net::syscalls::listen(sockfd.as_fd(), backlog)
543 }
544
545 /// `accept(fd, NULL, NULL)`—Accepts an incoming connection.
546 ///
547 /// Use [`acceptfrom`] to retrieve the peer address.
548 ///
549 /// POSIX guarantees that `accept` will use the lowest unused file descriptor,
550 /// however it is not safe in general to rely on this, as file descriptors may
551 /// be unexpectedly allocated on other threads or in libraries.
552 ///
553 /// # References
554 /// - [Beej's Guide to Network Programming]
555 /// - [POSIX]
556 /// - [Linux]
557 /// - [Apple]
558 /// - [Winsock]
559 /// - [FreeBSD]
560 /// - [NetBSD]
561 /// - [OpenBSD]
562 /// - [DragonFly BSD]
563 /// - [illumos]
564 /// - [glibc]
565 ///
566 /// [Beej's Guide to Network Programming]: https://beej.us/guide/bgnet/html/split/system-calls-or-bust.html#acceptthank-you-for-calling-port-3490.
567 /// [POSIX]: https://pubs.opengroup.org/onlinepubs/9699919799/functions/accept.html
568 /// [Linux]: https://man7.org/linux/man-pages/man2/accept.2.html
569 /// [Apple]: https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man2/accept.2.html
570 /// [Winsock]: https://docs.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-accept
571 /// [FreeBSD]: https://man.freebsd.org/cgi/man.cgi?query=accept&sektion=2
572 /// [NetBSD]: https://man.netbsd.org/accept.2
573 /// [OpenBSD]: https://man.openbsd.org/accept.2
574 /// [DragonFly BSD]: https://man.dragonflybsd.org/?command=accept&section=2
575 /// [illumos]: https://illumos.org/man/3SOCKET/accept
576 /// [glibc]: https://www.gnu.org/software/libc/manual/html_node/Accepting-Connections.html
577 #[inline]
578 pub fn accept<Fd: AsFd>(sockfd: Fd) -> io::Result<OwnedFd> {
579 backend::net::syscalls::accept(sockfd.as_fd())
580 }
581
582 /// `accept4(fd, NULL, NULL, flags)`—Accepts an incoming connection, with
583 /// flags.
584 ///
585 /// Use [`acceptfrom_with`] to retrieve the peer address.
586 ///
587 /// Even though POSIX guarantees that this will use the lowest unused file
588 /// descriptor, it is not safe in general to rely on this, as file descriptors
589 /// may be unexpectedly allocated on other threads or in libraries.
590 ///
591 /// `accept_with` is the same as [`accept`] but adds an additional flags
592 /// operand.
593 ///
594 /// # References
595 /// - [Linux]
596 /// - [FreeBSD]
597 /// - [NetBSD]
598 /// - [OpenBSD]
599 /// - [DragonFly BSD]
600 /// - [illumos]
601 ///
602 /// [Linux]: https://man7.org/linux/man-pages/man2/accept4.2.html
603 /// [FreeBSD]: https://man.freebsd.org/cgi/man.cgi?query=accept4&sektion=2
604 /// [NetBSD]: https://man.netbsd.org/accept4.2
605 /// [OpenBSD]: https://man.openbsd.org/accept4.2
606 /// [DragonFly BSD]: https://man.dragonflybsd.org/?command=accept4&section=2
607 /// [illumos]: https://illumos.org/man/3SOCKET/accept4
608 #[inline]
609 #[doc(alias = "accept4")]
610 pub fn accept_with<Fd: AsFd>(sockfd: Fd, flags: SocketFlags) -> io::Result<OwnedFd> {
611 backend::net::syscalls::accept_with(sockfd.as_fd(), flags)
612 }
613
614 /// `accept(fd, &addr, &len)`—Accepts an incoming connection and returns the
615 /// peer address.
616 ///
617 /// Use [`accept`] if the peer address isn't needed.
618 ///
619 /// # References
620 /// - [Beej's Guide to Network Programming]
621 /// - [POSIX]
622 /// - [Linux]
623 /// - [Apple]
624 /// - [Winsock]
625 /// - [FreeBSD]
626 /// - [NetBSD]
627 /// - [OpenBSD]
628 /// - [DragonFly BSD]
629 /// - [illumos]
630 /// - [glibc]
631 ///
632 /// [Beej's Guide to Network Programming]: https://beej.us/guide/bgnet/html/split/system-calls-or-bust.html#acceptthank-you-for-calling-port-3490.
633 /// [POSIX]: https://pubs.opengroup.org/onlinepubs/9699919799/functions/accept.html
634 /// [Linux]: https://man7.org/linux/man-pages/man2/accept.2.html
635 /// [Apple]: https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man2/accept.2.html
636 /// [Winsock]: https://docs.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-accept
637 /// [FreeBSD]: https://man.freebsd.org/cgi/man.cgi?query=accept&sektion=2
638 /// [NetBSD]: https://man.netbsd.org/accept.2
639 /// [OpenBSD]: https://man.openbsd.org/accept.2
640 /// [DragonFly BSD]: https://man.dragonflybsd.org/?command=accept&section=2
641 /// [illumos]: https://illumos.org/man/3SOCKET/accept
642 /// [glibc]: https://www.gnu.org/software/libc/manual/html_node/Accepting-Connections.html
643 #[inline]
644 #[doc(alias = "accept")]
645 pub fn acceptfrom<Fd: AsFd>(sockfd: Fd) -> io::Result<(OwnedFd, Option<SocketAddrAny>)> {
646 backend::net::syscalls::acceptfrom(sockfd.as_fd())
647 }
648
649 /// `accept4(fd, &addr, &len, flags)`—Accepts an incoming connection and
650 /// returns the peer address, with flags.
651 ///
652 /// Use [`accept_with`] if the peer address isn't needed.
653 ///
654 /// `acceptfrom_with` is the same as [`acceptfrom`] but adds an additional
655 /// flags operand.
656 ///
657 /// # References
658 /// - [Linux]
659 /// - [FreeBSD]
660 /// - [NetBSD]
661 /// - [OpenBSD]
662 /// - [DragonFly BSD]
663 /// - [illumos]
664 ///
665 /// [Linux]: https://man7.org/linux/man-pages/man2/accept4.2.html
666 /// [FreeBSD]: https://man.freebsd.org/cgi/man.cgi?query=accept4&sektion=2
667 /// [NetBSD]: https://man.netbsd.org/accept4.2
668 /// [OpenBSD]: https://man.openbsd.org/accept4.2
669 /// [DragonFly BSD]: https://man.dragonflybsd.org/?command=accept4&section=2
670 /// [illumos]: https://illumos.org/man/3SOCKET/accept4
671 #[inline]
672 #[doc(alias = "accept4")]
673 pub fn acceptfrom_with<Fd: AsFd>(
674 sockfd: Fd,
675 flags: SocketFlags,
676 ) -> io::Result<(OwnedFd, Option<SocketAddrAny>)> {
677 backend::net::syscalls::acceptfrom_with(sockfd.as_fd(), flags)
678 }
679
680 /// `shutdown(fd, how)`—Closes the read and/or write sides of a stream.
681 ///
682 /// # References
683 /// - [Beej's Guide to Network Programming]
684 /// - [POSIX]
685 /// - [Linux]
686 /// - [Apple]
687 /// - [Winsock]
688 /// - [FreeBSD]
689 /// - [NetBSD]
690 /// - [OpenBSD]
691 /// - [DragonFly BSD]
692 /// - [illumos]
693 /// - [glibc]
694 ///
695 /// [Beej's Guide to Network Programming]: https://beej.us/guide/bgnet/html/split/system-calls-or-bust.html#close-and-shutdownget-outta-my-face
696 /// [POSIX]: https://pubs.opengroup.org/onlinepubs/9699919799/functions/shutdown.html
697 /// [Linux]: https://man7.org/linux/man-pages/man2/shutdown.2.html
698 /// [Apple]: https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man2/shutdown.2.html
699 /// [Winsock]: https://docs.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-shutdown
700 /// [FreeBSD]: https://man.freebsd.org/cgi/man.cgi?query=shutdown&sektion=2
701 /// [NetBSD]: https://man.netbsd.org/shutdown.2
702 /// [OpenBSD]: https://man.openbsd.org/shutdown.2
703 /// [DragonFly BSD]: https://man.dragonflybsd.org/?command=shutdown&section=2
704 /// [illumos]: https://illumos.org/man/3SOCKET/shutdown
705 /// [glibc]: https://www.gnu.org/software/libc/manual/html_node/Closing-a-Socket.html
706 #[inline]
707 pub fn shutdown<Fd: AsFd>(sockfd: Fd, how: Shutdown) -> io::Result<()> {
708 backend::net::syscalls::shutdown(sockfd.as_fd(), how)
709 }
710
711 /// `getsockname(fd, addr, len)`—Returns the address a socket is bound to.
712 ///
713 /// # References
714 /// - [POSIX]
715 /// - [Linux]
716 /// - [Apple]
717 /// - [Winsock]
718 /// - [FreeBSD]
719 /// - [NetBSD]
720 /// - [OpenBSD]
721 /// - [DragonFly BSD]
722 /// - [illumos]
723 /// - [glibc]
724 ///
725 /// [POSIX]: https://pubs.opengroup.org/onlinepubs/9699919799/functions/getsockname.html
726 /// [Linux]: https://man7.org/linux/man-pages/man2/getsockname.2.html
727 /// [Apple]: https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man2/getsockname.2.html
728 /// [Winsock]: https://docs.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-getsockname
729 /// [FreeBSD]: https://man.freebsd.org/cgi/man.cgi?query=getsockname&sektion=2
730 /// [NetBSD]: https://man.netbsd.org/getsockname.2
731 /// [OpenBSD]: https://man.openbsd.org/getsockname.2
732 /// [DragonFly BSD]: https://man.dragonflybsd.org/?command=getsockname&section=2
733 /// [illumos]: https://illumos.org/man/3SOCKET/getsockname
734 /// [glibc]: https://www.gnu.org/software/libc/manual/html_node/Reading-Address.html
735 #[inline]
736 pub fn getsockname<Fd: AsFd>(sockfd: Fd) -> io::Result<SocketAddrAny> {
737 backend::net::syscalls::getsockname(sockfd.as_fd())
738 }
739
740 /// `getpeername(fd, addr, len)`—Returns the address a socket is connected
741 /// to.
742 ///
743 /// # References
744 /// - [Beej's Guide to Network Programming]
745 /// - [POSIX]
746 /// - [Linux]
747 /// - [Apple]
748 /// - [Winsock]
749 /// - [FreeBSD]
750 /// - [NetBSD]
751 /// - [OpenBSD]
752 /// - [DragonFly BSD]
753 /// - [illumos]
754 /// - [glibc]
755 ///
756 /// [Beej's Guide to Network Programming]: https://beej.us/guide/bgnet/html/split/system-calls-or-bust.html#getpeernamewho-are-you
757 /// [POSIX]: https://pubs.opengroup.org/onlinepubs/9699919799/functions/getpeername.html
758 /// [Linux]: https://man7.org/linux/man-pages/man2/getpeername.2.html
759 /// [Apple]: https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man2/getpeername.2.html
760 /// [Winsock]: https://docs.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-getpeername
761 /// [FreeBSD]: https://man.freebsd.org/cgi/man.cgi?query=getpeername&sektion=2
762 /// [NetBSD]: https://man.netbsd.org/getpeername.2
763 /// [OpenBSD]: https://man.openbsd.org/getpeername.2
764 /// [DragonFly BSD]: https://man.dragonflybsd.org/?command=getpeername&section=2
765 /// [illumos]: https://illumos.org/man/3SOCKET/getpeername
766 /// [glibc]: https://www.gnu.org/software/libc/manual/html_node/Who-is-Connected.html
767 #[inline]
768 pub fn getpeername<Fd: AsFd>(sockfd: Fd) -> io::Result<Option<SocketAddrAny>> {
769 backend::net::syscalls::getpeername(sockfd.as_fd())
770 }