1use std::hash::Hash;
2use std::mem::{self, size_of, MaybeUninit};
3use std::net::{SocketAddr, SocketAddrV4, SocketAddrV6};
4use std::path::Path;
5use std::{fmt, io, ptr};
6
7#[cfg(windows)]
8use windows_sys::Win32::Networking::WinSock::SOCKADDR_IN6_0;
9
10use crate::sys::{
11 c_int, sa_family_t, sockaddr, sockaddr_in, sockaddr_in6, sockaddr_storage, socklen_t, AF_INET,
12 AF_INET6, AF_UNIX,
13};
14use crate::Domain;
15
16/// The address of a socket.
17///
18/// `SockAddr`s may be constructed directly to and from the standard library
19/// [`SocketAddr`], [`SocketAddrV4`], and [`SocketAddrV6`] types.
20#[derive(Clone)]
21pub struct SockAddr {
22 storage: sockaddr_storage,
23 len: socklen_t,
24}
25
26#[allow(clippy::len_without_is_empty)]
27impl SockAddr {
28 /// Create a `SockAddr` from the underlying storage and its length.
29 ///
30 /// # Safety
31 ///
32 /// Caller must ensure that the address family and length match the type of
33 /// storage address. For example if `storage.ss_family` is set to `AF_INET`
34 /// the `storage` must be initialised as `sockaddr_in`, setting the content
35 /// and length appropriately.
36 ///
37 /// # Examples
38 ///
39 /// ```
40 /// # fn main() -> std::io::Result<()> {
41 /// # #[cfg(unix)] {
42 /// use std::io;
43 /// use std::mem;
44 /// use std::os::unix::io::AsRawFd;
45 ///
46 /// use socket2::{SockAddr, Socket, Domain, Type};
47 ///
48 /// let socket = Socket::new(Domain::IPV4, Type::STREAM, None)?;
49 ///
50 /// // Initialise a `SocketAddr` byte calling `getsockname(2)`.
51 /// let mut addr_storage: libc::sockaddr_storage = unsafe { mem::zeroed() };
52 /// let mut len = mem::size_of_val(&addr_storage) as libc::socklen_t;
53 ///
54 /// // The `getsockname(2)` system call will intiliase `storage` for
55 /// // us, setting `len` to the correct length.
56 /// let res = unsafe {
57 /// libc::getsockname(
58 /// socket.as_raw_fd(),
59 /// (&mut addr_storage as *mut libc::sockaddr_storage).cast(),
60 /// &mut len,
61 /// )
62 /// };
63 /// if res == -1 {
64 /// return Err(io::Error::last_os_error());
65 /// }
66 ///
67 /// let address = unsafe { SockAddr::new(addr_storage, len) };
68 /// # drop(address);
69 /// # }
70 /// # Ok(())
71 /// # }
72 /// ```
73 pub const unsafe fn new(storage: sockaddr_storage, len: socklen_t) -> SockAddr {
74 SockAddr { storage, len }
75 }
76
77 /// Initialise a `SockAddr` by calling the function `init`.
78 ///
79 /// The type of the address storage and length passed to the function `init`
80 /// is OS/architecture specific.
81 ///
82 /// The address is zeroed before `init` is called and is thus valid to
83 /// dereference and read from. The length initialised to the maximum length
84 /// of the storage.
85 ///
86 /// # Safety
87 ///
88 /// Caller must ensure that the address family and length match the type of
89 /// storage address. For example if `storage.ss_family` is set to `AF_INET`
90 /// the `storage` must be initialised as `sockaddr_in`, setting the content
91 /// and length appropriately.
92 ///
93 /// # Examples
94 ///
95 /// ```
96 /// # fn main() -> std::io::Result<()> {
97 /// # #[cfg(unix)] {
98 /// use std::io;
99 /// use std::os::unix::io::AsRawFd;
100 ///
101 /// use socket2::{SockAddr, Socket, Domain, Type};
102 ///
103 /// let socket = Socket::new(Domain::IPV4, Type::STREAM, None)?;
104 ///
105 /// // Initialise a `SocketAddr` byte calling `getsockname(2)`.
106 /// let (_, address) = unsafe {
107 /// SockAddr::try_init(|addr_storage, len| {
108 /// // The `getsockname(2)` system call will intiliase `storage` for
109 /// // us, setting `len` to the correct length.
110 /// if libc::getsockname(socket.as_raw_fd(), addr_storage.cast(), len) == -1 {
111 /// Err(io::Error::last_os_error())
112 /// } else {
113 /// Ok(())
114 /// }
115 /// })
116 /// }?;
117 /// # drop(address);
118 /// # }
119 /// # Ok(())
120 /// # }
121 /// ```
122 pub unsafe fn try_init<F, T>(init: F) -> io::Result<(T, SockAddr)>
123 where
124 F: FnOnce(*mut sockaddr_storage, *mut socklen_t) -> io::Result<T>,
125 {
126 const STORAGE_SIZE: socklen_t = size_of::<sockaddr_storage>() as socklen_t;
127 // NOTE: `SockAddr::unix` depends on the storage being zeroed before
128 // calling `init`.
129 // NOTE: calling `recvfrom` with an empty buffer also depends on the
130 // storage being zeroed before calling `init` as the OS might not
131 // initialise it.
132 let mut storage = MaybeUninit::<sockaddr_storage>::zeroed();
133 let mut len = STORAGE_SIZE;
134 init(storage.as_mut_ptr(), &mut len).map(|res| {
135 debug_assert!(len <= STORAGE_SIZE, "overflown address storage");
136 let addr = SockAddr {
137 // Safety: zeroed-out `sockaddr_storage` is valid, caller must
138 // ensure at least `len` bytes are valid.
139 storage: storage.assume_init(),
140 len,
141 };
142 (res, addr)
143 })
144 }
145
146 /// Constructs a `SockAddr` with the family `AF_UNIX` and the provided path.
147 ///
148 /// Returns an error if the path is longer than `SUN_LEN`.
149 pub fn unix<P>(path: P) -> io::Result<SockAddr>
150 where
151 P: AsRef<Path>,
152 {
153 crate::sys::unix_sockaddr(path.as_ref())
154 }
155
156 /// Set the length of the address.
157 ///
158 /// # Safety
159 ///
160 /// Caller must ensure that the address up to `length` bytes are properly
161 /// initialised.
162 pub unsafe fn set_length(&mut self, length: socklen_t) {
163 self.len = length;
164 }
165
166 /// Returns this address's family.
167 pub const fn family(&self) -> sa_family_t {
168 self.storage.ss_family
169 }
170
171 /// Returns this address's `Domain`.
172 pub const fn domain(&self) -> Domain {
173 Domain(self.storage.ss_family as c_int)
174 }
175
176 /// Returns the size of this address in bytes.
177 pub const fn len(&self) -> socklen_t {
178 self.len
179 }
180
181 /// Returns a raw pointer to the address.
182 pub const fn as_ptr(&self) -> *const sockaddr {
183 ptr::addr_of!(self.storage).cast()
184 }
185
186 /// Retuns the address as the storage.
187 pub const fn as_storage(self) -> sockaddr_storage {
188 self.storage
189 }
190
191 /// Returns true if this address is in the `AF_INET` (IPv4) family, false otherwise.
192 pub const fn is_ipv4(&self) -> bool {
193 self.storage.ss_family == AF_INET as sa_family_t
194 }
195
196 /// Returns true if this address is in the `AF_INET6` (IPv6) family, false
197 /// otherwise.
198 pub const fn is_ipv6(&self) -> bool {
199 self.storage.ss_family == AF_INET6 as sa_family_t
200 }
201
202 /// Returns true if this address is of a unix socket (for local interprocess communication),
203 /// i.e. it is from the `AF_UNIX` family, false otherwise.
204 pub fn is_unix(&self) -> bool {
205 self.storage.ss_family == AF_UNIX as sa_family_t
206 }
207
208 /// Returns this address as a `SocketAddr` if it is in the `AF_INET` (IPv4)
209 /// or `AF_INET6` (IPv6) family, otherwise returns `None`.
210 pub fn as_socket(&self) -> Option<SocketAddr> {
211 if self.storage.ss_family == AF_INET as sa_family_t {
212 // SAFETY: if the `ss_family` field is `AF_INET` then storage must
213 // be a `sockaddr_in`.
214 let addr = unsafe { &*(ptr::addr_of!(self.storage).cast::<sockaddr_in>()) };
215 let ip = crate::sys::from_in_addr(addr.sin_addr);
216 let port = u16::from_be(addr.sin_port);
217 Some(SocketAddr::V4(SocketAddrV4::new(ip, port)))
218 } else if self.storage.ss_family == AF_INET6 as sa_family_t {
219 // SAFETY: if the `ss_family` field is `AF_INET6` then storage must
220 // be a `sockaddr_in6`.
221 let addr = unsafe { &*(ptr::addr_of!(self.storage).cast::<sockaddr_in6>()) };
222 let ip = crate::sys::from_in6_addr(addr.sin6_addr);
223 let port = u16::from_be(addr.sin6_port);
224 Some(SocketAddr::V6(SocketAddrV6::new(
225 ip,
226 port,
227 addr.sin6_flowinfo,
228 #[cfg(unix)]
229 addr.sin6_scope_id,
230 #[cfg(windows)]
231 unsafe {
232 addr.Anonymous.sin6_scope_id
233 },
234 )))
235 } else {
236 None
237 }
238 }
239
240 /// Returns this address as a [`SocketAddrV4`] if it is in the `AF_INET`
241 /// family.
242 pub fn as_socket_ipv4(&self) -> Option<SocketAddrV4> {
243 match self.as_socket() {
244 Some(SocketAddr::V4(addr)) => Some(addr),
245 _ => None,
246 }
247 }
248
249 /// Returns this address as a [`SocketAddrV6`] if it is in the `AF_INET6`
250 /// family.
251 pub fn as_socket_ipv6(&self) -> Option<SocketAddrV6> {
252 match self.as_socket() {
253 Some(SocketAddr::V6(addr)) => Some(addr),
254 _ => None,
255 }
256 }
257
258 /// Returns the initialised storage bytes.
259 fn as_bytes(&self) -> &[u8] {
260 // SAFETY: `self.storage` is a C struct which can always be treated a
261 // slice of bytes. Furthermore, we ensure we don't read any unitialised
262 // bytes by using `self.len`.
263 unsafe { std::slice::from_raw_parts(self.as_ptr().cast(), self.len as usize) }
264 }
265}
266
267impl From<SocketAddr> for SockAddr {
268 fn from(addr: SocketAddr) -> SockAddr {
269 match addr {
270 SocketAddr::V4(addr: SocketAddrV4) => addr.into(),
271 SocketAddr::V6(addr: SocketAddrV6) => addr.into(),
272 }
273 }
274}
275
276impl From<SocketAddrV4> for SockAddr {
277 fn from(addr: SocketAddrV4) -> SockAddr {
278 // SAFETY: a `sockaddr_storage` of all zeros is valid.
279 let mut storage = unsafe { mem::zeroed::<sockaddr_storage>() };
280 let len = {
281 let storage = unsafe { &mut *ptr::addr_of_mut!(storage).cast::<sockaddr_in>() };
282 storage.sin_family = AF_INET as sa_family_t;
283 storage.sin_port = addr.port().to_be();
284 storage.sin_addr = crate::sys::to_in_addr(addr.ip());
285 storage.sin_zero = Default::default();
286 mem::size_of::<sockaddr_in>() as socklen_t
287 };
288 #[cfg(any(
289 target_os = "dragonfly",
290 target_os = "freebsd",
291 target_os = "haiku",
292 target_os = "hermit",
293 target_os = "ios",
294 target_os = "visionos",
295 target_os = "macos",
296 target_os = "netbsd",
297 target_os = "nto",
298 target_os = "openbsd",
299 target_os = "tvos",
300 target_os = "vxworks",
301 target_os = "watchos",
302 ))]
303 {
304 storage.ss_len = len as u8;
305 }
306 SockAddr { storage, len }
307 }
308}
309
310impl From<SocketAddrV6> for SockAddr {
311 fn from(addr: SocketAddrV6) -> SockAddr {
312 // SAFETY: a `sockaddr_storage` of all zeros is valid.
313 let mut storage = unsafe { mem::zeroed::<sockaddr_storage>() };
314 let len = {
315 let storage = unsafe { &mut *ptr::addr_of_mut!(storage).cast::<sockaddr_in6>() };
316 storage.sin6_family = AF_INET6 as sa_family_t;
317 storage.sin6_port = addr.port().to_be();
318 storage.sin6_addr = crate::sys::to_in6_addr(addr.ip());
319 storage.sin6_flowinfo = addr.flowinfo();
320 #[cfg(unix)]
321 {
322 storage.sin6_scope_id = addr.scope_id();
323 }
324 #[cfg(windows)]
325 {
326 storage.Anonymous = SOCKADDR_IN6_0 {
327 sin6_scope_id: addr.scope_id(),
328 };
329 }
330 mem::size_of::<sockaddr_in6>() as socklen_t
331 };
332 #[cfg(any(
333 target_os = "dragonfly",
334 target_os = "freebsd",
335 target_os = "haiku",
336 target_os = "hermit",
337 target_os = "ios",
338 target_os = "visionos",
339 target_os = "macos",
340 target_os = "netbsd",
341 target_os = "nto",
342 target_os = "openbsd",
343 target_os = "tvos",
344 target_os = "vxworks",
345 target_os = "watchos",
346 ))]
347 {
348 storage.ss_len = len as u8;
349 }
350 SockAddr { storage, len }
351 }
352}
353
354impl fmt::Debug for SockAddr {
355 fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
356 let mut f: DebugStruct<'_, '_> = fmt.debug_struct(name:"SockAddr");
357 #[cfg(any(
358 target_os = "dragonfly",
359 target_os = "freebsd",
360 target_os = "haiku",
361 target_os = "hermit",
362 target_os = "ios",
363 target_os = "visionos",
364 target_os = "macos",
365 target_os = "netbsd",
366 target_os = "nto",
367 target_os = "openbsd",
368 target_os = "tvos",
369 target_os = "vxworks",
370 target_os = "watchos",
371 ))]
372 f.field("ss_len", &self.storage.ss_len);
373 f&mut DebugStruct<'_, '_>.field("ss_family", &self.storage.ss_family)
374 .field(name:"len", &self.len)
375 .finish()
376 }
377}
378
379impl PartialEq for SockAddr {
380 fn eq(&self, other: &Self) -> bool {
381 self.as_bytes() == other.as_bytes()
382 }
383}
384
385impl Eq for SockAddr {}
386
387impl Hash for SockAddr {
388 fn hash<H: std::hash::Hasher>(&self, state: &mut H) {
389 self.as_bytes().hash(state);
390 }
391}
392
393#[cfg(test)]
394mod tests {
395 use super::*;
396
397 #[test]
398 fn ipv4() {
399 use std::net::Ipv4Addr;
400 let std = SocketAddrV4::new(Ipv4Addr::new(1, 2, 3, 4), 9876);
401 let addr = SockAddr::from(std);
402 assert!(addr.is_ipv4());
403 assert!(!addr.is_ipv6());
404 assert!(!addr.is_unix());
405 assert_eq!(addr.family(), AF_INET as sa_family_t);
406 assert_eq!(addr.domain(), Domain::IPV4);
407 assert_eq!(addr.len(), size_of::<sockaddr_in>() as socklen_t);
408 assert_eq!(addr.as_socket(), Some(SocketAddr::V4(std)));
409 assert_eq!(addr.as_socket_ipv4(), Some(std));
410 assert!(addr.as_socket_ipv6().is_none());
411
412 let addr = SockAddr::from(SocketAddr::from(std));
413 assert_eq!(addr.family(), AF_INET as sa_family_t);
414 assert_eq!(addr.len(), size_of::<sockaddr_in>() as socklen_t);
415 assert_eq!(addr.as_socket(), Some(SocketAddr::V4(std)));
416 assert_eq!(addr.as_socket_ipv4(), Some(std));
417 assert!(addr.as_socket_ipv6().is_none());
418 #[cfg(unix)]
419 {
420 assert!(addr.as_pathname().is_none());
421 assert!(addr.as_abstract_namespace().is_none());
422 }
423 }
424
425 #[test]
426 fn ipv6() {
427 use std::net::Ipv6Addr;
428 let std = SocketAddrV6::new(Ipv6Addr::new(1, 2, 3, 4, 5, 6, 7, 8), 9876, 11, 12);
429 let addr = SockAddr::from(std);
430 assert!(addr.is_ipv6());
431 assert!(!addr.is_ipv4());
432 assert!(!addr.is_unix());
433 assert_eq!(addr.family(), AF_INET6 as sa_family_t);
434 assert_eq!(addr.domain(), Domain::IPV6);
435 assert_eq!(addr.len(), size_of::<sockaddr_in6>() as socklen_t);
436 assert_eq!(addr.as_socket(), Some(SocketAddr::V6(std)));
437 assert!(addr.as_socket_ipv4().is_none());
438 assert_eq!(addr.as_socket_ipv6(), Some(std));
439
440 let addr = SockAddr::from(SocketAddr::from(std));
441 assert_eq!(addr.family(), AF_INET6 as sa_family_t);
442 assert_eq!(addr.len(), size_of::<sockaddr_in6>() as socklen_t);
443 assert_eq!(addr.as_socket(), Some(SocketAddr::V6(std)));
444 assert!(addr.as_socket_ipv4().is_none());
445 assert_eq!(addr.as_socket_ipv6(), Some(std));
446 #[cfg(unix)]
447 {
448 assert!(addr.as_pathname().is_none());
449 assert!(addr.as_abstract_namespace().is_none());
450 }
451 }
452
453 #[test]
454 fn ipv4_eq() {
455 use std::net::Ipv4Addr;
456
457 let std1 = SocketAddrV4::new(Ipv4Addr::new(1, 2, 3, 4), 9876);
458 let std2 = SocketAddrV4::new(Ipv4Addr::new(5, 6, 7, 8), 8765);
459
460 test_eq(
461 SockAddr::from(std1),
462 SockAddr::from(std1),
463 SockAddr::from(std2),
464 );
465 }
466
467 #[test]
468 fn ipv4_hash() {
469 use std::net::Ipv4Addr;
470
471 let std1 = SocketAddrV4::new(Ipv4Addr::new(1, 2, 3, 4), 9876);
472 let std2 = SocketAddrV4::new(Ipv4Addr::new(5, 6, 7, 8), 8765);
473
474 test_hash(
475 SockAddr::from(std1),
476 SockAddr::from(std1),
477 SockAddr::from(std2),
478 );
479 }
480
481 #[test]
482 fn ipv6_eq() {
483 use std::net::Ipv6Addr;
484
485 let std1 = SocketAddrV6::new(Ipv6Addr::new(1, 2, 3, 4, 5, 6, 7, 8), 9876, 11, 12);
486 let std2 = SocketAddrV6::new(Ipv6Addr::new(3, 4, 5, 6, 7, 8, 9, 0), 7654, 13, 14);
487
488 test_eq(
489 SockAddr::from(std1),
490 SockAddr::from(std1),
491 SockAddr::from(std2),
492 );
493 }
494
495 #[test]
496 fn ipv6_hash() {
497 use std::net::Ipv6Addr;
498
499 let std1 = SocketAddrV6::new(Ipv6Addr::new(1, 2, 3, 4, 5, 6, 7, 8), 9876, 11, 12);
500 let std2 = SocketAddrV6::new(Ipv6Addr::new(3, 4, 5, 6, 7, 8, 9, 0), 7654, 13, 14);
501
502 test_hash(
503 SockAddr::from(std1),
504 SockAddr::from(std1),
505 SockAddr::from(std2),
506 );
507 }
508
509 #[test]
510 fn ipv4_ipv6_eq() {
511 use std::net::Ipv4Addr;
512 use std::net::Ipv6Addr;
513
514 let std1 = SocketAddrV4::new(Ipv4Addr::new(1, 2, 3, 4), 9876);
515 let std2 = SocketAddrV6::new(Ipv6Addr::new(1, 2, 3, 4, 5, 6, 7, 8), 9876, 11, 12);
516
517 test_eq(
518 SockAddr::from(std1),
519 SockAddr::from(std1),
520 SockAddr::from(std2),
521 );
522
523 test_eq(
524 SockAddr::from(std2),
525 SockAddr::from(std2),
526 SockAddr::from(std1),
527 );
528 }
529
530 #[test]
531 fn ipv4_ipv6_hash() {
532 use std::net::Ipv4Addr;
533 use std::net::Ipv6Addr;
534
535 let std1 = SocketAddrV4::new(Ipv4Addr::new(1, 2, 3, 4), 9876);
536 let std2 = SocketAddrV6::new(Ipv6Addr::new(1, 2, 3, 4, 5, 6, 7, 8), 9876, 11, 12);
537
538 test_hash(
539 SockAddr::from(std1),
540 SockAddr::from(std1),
541 SockAddr::from(std2),
542 );
543
544 test_hash(
545 SockAddr::from(std2),
546 SockAddr::from(std2),
547 SockAddr::from(std1),
548 );
549 }
550
551 #[allow(clippy::eq_op)] // allow a0 == a0 check
552 fn test_eq(a0: SockAddr, a1: SockAddr, b: SockAddr) {
553 assert!(a0 == a0);
554 assert!(a0 == a1);
555 assert!(a1 == a0);
556 assert!(a0 != b);
557 assert!(b != a0);
558 }
559
560 fn test_hash(a0: SockAddr, a1: SockAddr, b: SockAddr) {
561 assert!(calculate_hash(&a0) == calculate_hash(&a0));
562 assert!(calculate_hash(&a0) == calculate_hash(&a1));
563 // technically unequal values can have the same hash, in this case x != z and both have different hashes
564 assert!(calculate_hash(&a0) != calculate_hash(&b));
565 }
566
567 fn calculate_hash(x: &SockAddr) -> u64 {
568 use std::collections::hash_map::DefaultHasher;
569 use std::hash::Hasher;
570
571 let mut hasher = DefaultHasher::new();
572 x.hash(&mut hasher);
573 hasher.finish()
574 }
575}
576