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