1use crate::fd::OwnedFd;
2use crate::net::{SocketAddr, SocketAddrAny, SocketAddrV4, SocketAddrV6};
3use crate::{backend, io};
4use backend::fd::{AsFd, BorrowedFd};
5
6#[cfg(target_os = "linux")]
7use crate::net::xdp::SocketAddrXdp;
8pub use crate::net::{AddressFamily, Protocol, Shutdown, SocketFlags, SocketType};
9#[cfg(unix)]
10pub 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/9799919799/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://sourceware.org/glibc/manual/latest/html_node/Creating-a-Socket.html
45#[inline]
46pub fn socket(
47 domain: AddressFamily,
48 type_: SocketType,
49 protocol: Option<Protocol>,
50) -> io::Result<OwnedFd> {
51 backend::net::syscalls::socket(family: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/9799919799/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://sourceware.org/glibc/manual/latest/html_node/Creating-a-Socket.html
88#[doc(alias("socket"))]
89#[inline]
90pub 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(family: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/9799919799/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://sourceware.org/glibc/manual/latest/html_node/Setting-Address.html
125pub fn bind<Fd: AsFd>(sockfd: Fd, addr: &SocketAddr) -> io::Result<()> {
126 _bind(sockfd.as_fd(), addr)
127}
128
129fn _bind(sockfd: BorrowedFd<'_>, addr: &SocketAddr) -> io::Result<()> {
130 match addr {
131 SocketAddr::V4(v4: &SocketAddrV4) => backend::net::syscalls::bind_v4(fd:sockfd, addr:v4),
132 SocketAddr::V6(v6: &SocketAddrV6) => backend::net::syscalls::bind_v6(fd:sockfd, addr: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/9799919799/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://sourceware.org/glibc/manual/latest/html_node/Setting-Address.html
162#[doc(alias = "bind")]
163pub fn bind_any<Fd: AsFd>(sockfd: Fd, addr: &SocketAddrAny) -> io::Result<()> {
164 _bind_any(sockfd.as_fd(), addr)
165}
166
167fn _bind_any(sockfd: BorrowedFd<'_>, addr: &SocketAddrAny) -> io::Result<()> {
168 match addr {
169 SocketAddrAny::V4(v4: &SocketAddrV4) => backend::net::syscalls::bind_v4(fd:sockfd, addr:v4),
170 SocketAddrAny::V6(v6: &SocketAddrV6) => backend::net::syscalls::bind_v6(fd:sockfd, addr:v6),
171 #[cfg(unix)]
172 SocketAddrAny::Unix(unix: &SocketAddrUnix) => backend::net::syscalls::bind_unix(fd:sockfd, addr:unix),
173 #[cfg(target_os = "linux")]
174 SocketAddrAny::Xdp(xdp: &SocketAddrXdp) => backend::net::syscalls::bind_xdp(fd:sockfd, addr: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/9799919799/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://sourceware.org/glibc/manual/latest/html_node/Setting-Address.html
205#[inline]
206#[doc(alias = "bind")]
207pub 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/9799919799/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://sourceware.org/glibc/manual/latest/html_node/Setting-Address.html
238#[inline]
239#[doc(alias = "bind")]
240pub 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/9799919799/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://sourceware.org/glibc/manual/latest/html_node/Setting-Address.html
271#[cfg(unix)]
272#[inline]
273#[doc(alias = "bind")]
274pub 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")]
288pub 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/9799919799/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://sourceware.org/glibc/manual/latest/html_node/Connecting.html
322/// [`Errno::WOULDBLOCK`]: io::Errno::WOULDBLOCK
323pub fn connect<Fd: AsFd>(sockfd: Fd, addr: &SocketAddr) -> io::Result<()> {
324 _connect(sockfd.as_fd(), addr)
325}
326
327fn _connect(sockfd: BorrowedFd<'_>, addr: &SocketAddr) -> io::Result<()> {
328 match addr {
329 SocketAddr::V4(v4: &SocketAddrV4) => backend::net::syscalls::connect_v4(fd:sockfd, addr:v4),
330 SocketAddr::V6(v6: &SocketAddrV6) => backend::net::syscalls::connect_v6(fd:sockfd, addr: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/9799919799/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://sourceware.org/glibc/manual/latest/html_node/Connecting.html
360#[doc(alias = "connect")]
361pub fn connect_any<Fd: AsFd>(sockfd: Fd, addr: &SocketAddrAny) -> io::Result<()> {
362 _connect_any(sockfd.as_fd(), addr)
363}
364
365fn _connect_any(sockfd: BorrowedFd<'_>, addr: &SocketAddrAny) -> io::Result<()> {
366 match addr {
367 SocketAddrAny::V4(v4: &SocketAddrV4) => backend::net::syscalls::connect_v4(fd:sockfd, addr:v4),
368 SocketAddrAny::V6(v6: &SocketAddrV6) => backend::net::syscalls::connect_v6(fd:sockfd, addr:v6),
369 #[cfg(unix)]
370 SocketAddrAny::Unix(unix: &SocketAddrUnix) => backend::net::syscalls::connect_unix(fd:sockfd, addr: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/9799919799/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://sourceware.org/glibc/manual/latest/html_node/Connecting.html
403#[inline]
404#[doc(alias = "connect")]
405pub 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/9799919799/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://sourceware.org/glibc/manual/latest/html_node/Connecting.html
436#[inline]
437#[doc(alias = "connect")]
438pub 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/9799919799/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://sourceware.org/glibc/manual/latest/html_node/Connecting.html
469#[cfg(unix)]
470#[inline]
471#[doc(alias = "connect")]
472pub 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/9799919799/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://sourceware.org/glibc/manual/latest/html_node/Connecting.html
506/// [`Errno::AFNOSUPPORT`]: io::Errno::AFNOSUPPORT
507/// [`Errno::INVAL`]: io::Errno::INVAL
508#[inline]
509#[doc(alias = "connect")]
510pub 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/9799919799/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://sourceware.org/glibc/manual/latest/html_node/Listening.html
540#[inline]
541pub 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/9799919799/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://sourceware.org/glibc/manual/latest/html_node/Accepting-Connections.html
577#[inline]
578pub 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")]
610pub 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/9799919799/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://sourceware.org/glibc/manual/latest/html_node/Accepting-Connections.html
643#[inline]
644#[doc(alias = "accept")]
645pub 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")]
673pub 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/9799919799/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://sourceware.org/glibc/manual/latest/html_node/Closing-a-Socket.html
706#[inline]
707pub 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/9799919799/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://sourceware.org/glibc/manual/latest/html_node/Reading-Address.html
735#[inline]
736pub 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/9799919799/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://sourceware.org/glibc/manual/latest/html_node/Who-is-Connected.html
767#[inline]
768pub fn getpeername<Fd: AsFd>(sockfd: Fd) -> io::Result<Option<SocketAddrAny>> {
769 backend::net::syscalls::getpeername(sockfd.as_fd())
770}
771