RFC 2292 struct and constant definitions

[Skyb0rg007]

Description

This PR adds the structs and constants as defined by RFC 2292 - Advanced Sockets API for IPv6.
These constants are available for use in get/setsockopt on supported Unix platforms.
The operations defined on the icmp6_filter struct are defined as C macros, so the implementations are not included here.

Sources

https://github.com/bminor/glibc/blob/04e750e75b73957cf1c791535a3f4319534a52fc/inet/netinet/icmp6.h
https://github.com/kraj/musl/blob/kraj/master/include/netinet/icmp6.h
https://github.com/freebsd/freebsd-src/blob/9ae367d11de8abbdf53884836c9ba30908c5c8db/sys/netinet/icmp6.h

Also in the RFC: https://datatracker.ietf.org/doc/html/rfc2292#section-3.2

Checklist

Unfortunately I could not get the libc-tests working locally, so this PR is marked as draft.

• Relevant tests in libc-test/semver have been updated
• No placeholder or unstable values like *LAST or *MAX are
  included (see #3131)
• Tested locally (cd libc-test && cargo test --target mytarget);
  especially relevant for platforms that may not be checked in CI

@rustbot label +stable-nominated

[Skyb0rg007]

Alright, I need help. On *BSD platforms (FreeBSD, macOS, etc), struct in6_addr is defined as the union of uint32_t[4], uint16_t[8], and uint8_t[16], so Rust encodes it as [u8; 16] with repr(align(4)).

But the nd_(router|neighbor)_(solicit|advert) structures are marked as __packed (so their C alignment is 1), even though they include a in6_addr. Rust won't allow using repr(packed) on a struct containing a repr(align(...)) attribute, so I'm stuck.

Linux doesn't mark these structs as __packed, so there's no issue there.

[Skyb0rg007]

I see that some C macros such as the CMSG_ macros were added this package as const functions. It may make sense to add the ICMP6_FILTER_ macros too, especially since the icmp6_filter struct’s field name is different on Solaris.

[rustbot]

This PR was rebased onto a different main commit. Here's a range-diff highlighting what actually changed.

Rebasing is a normal part of keeping PRs up to date, so no action is needed—this note is just to help reviewers.

[tgross35]

Sorry for the delay, thank you for the changes here. The contents themselves look good, but I think they should be moved out of the root unix module.

View changes since this review

[tgross35]

For any reserved/padding fields, please make them private and wrap them in Padding

[Skyb0rg007]

Because these fields are part of a networking protocol, I don't think it makes sense to make these private. These fields were certainly just padding when the protocol was written, but in theory a new version of the IPv6 routing header could make use of these fields.

[tgross35]

Is there any use reading/writing them currently? My concern here is that if they do wind up being used, the fields may go through changes in C that we can't really mirror on the Rust side. E.g. they could rename the fields, possibly with a shim like #define ip6r0_new_nice_field_name ip6r0_reserved, or do something like split the u32 field into two u16s which is fine in C but breaking in Rust.

Open to thoughts but I'd rather err on the side of caution and make them private unless they're useful now.

[tgross35]

This struct should be opaque, can you make the fields private?

[Skyb0rg007]

The macros ICMP6_FILTER_SET(PASS|BLOCK)(ALL)? need to be defined for this type. Is the best way to handle this to make the fields pub (crate) and implement those macros as toplevel Rust functions?

[tgross35]

Seems like you may have started work here, but that seems reasonable to me.

[tgross35]

I think enabling these in the unix module is too high level; do we know anything about AIX, fuchsia, redox, etc?

Instead, could you put these into the linux_like and bsd modules? That will mean some duplication, but that's probably fine because it will simplify some of the repetitive padding config.

[tgross35]

What would be ideal here is to instead put these in src/new/common/bsd/{icmp6.rs,ip6.rs} and src/new/common/linux_like/{icmp6.rs,ip6.rs}, to match the header structure. The reexport them in src/new/{bionic_libc,musl,glibc,openbsd,freebsd,...}/{icmp6.rs,ip6.rs}, similar to what is done with unistd, and update src/new/mod.rs.

I won't require that because this has already been waiting a while, but eventually everything will move to that new structure so anything to help that is appreciated.

[Skyb0rg007]

I'm not sure about AIX, but Fuchsia does support icmp6_filter and RedoxOS (relibc) does not, at least for now.

I can try refactoring the code into those two files, but a lot of the differences with respect to alignment doesn't have a clean linux/bsd divide with android's implementation being more similar to that of the BSDs.
We might want to come up with a solution to the problem I remarked on here before I add definitions of these structs, because any solution will possibly change the public API for these structs anyways.

Also, I'm fine with a more major structural change to properly model the addition.
I have some more additions from RFC 3542 (the follow-on to 2292) which I plan to make a PR for after this is accepted. It just happens that the feature I was personally missing from libc was specified in the first Advanced IPv6 Sockets API RFC.

[tgross35]

I think it's okay to omit Fuchsia and others that aren't covered in CI for now. If a need comes up then usually one of their target maintainers does the addition, which also means they can run tests.

Could you split to BSD and Linux-like, then add a cfg(not(target_os = "android")) to the Linux version? I think that would still be cleaner.

Also, I'm fine with a more major structural change to properly model the addition. I have some more additions from RFC 3542 (the follow-on to 2292) which I plan to make a PR for after this is accepted. It just happens that the feature I was personally missing from libc was specified in the first Advanced IPv6 Sockets API RFC.

If you have more followups here then using the new structure might be nice, it's certainly more organized than the status quo. Up to you.

[tgross35]

Could you add links to the PR description to the headers for these other platforms that have the specific alignment requirements? (Looks like only glibc/musl/freebsd are there)

[Skyb0rg007]

Do you mean link to this PR, or directly link to the glibc/freebsd headers in the comment

[tgross35]

Just in the PR description, and at least for the tier 2 targets (Android, emscripten, MacOS). I'm just looking for something to compare the aligned/packed/etc config against.

[rustbot]

Reminder, once the PR becomes ready for a review, use @rustbot ready.

[Skyb0rg007]

After adding the ICMP_FILTER_ functions, I realize that the meaning of a set bit is different between Linux and BSD. I’m going to split that code out into a new PR since I think it’s going to be a decent effort to get tests written for that.