Remove ebpf_link_mark_as_legacy_mode

[Alan-Jowett]

Description

Resolves: #4675
Modify ebpf_program_atttach* APIs so they can emulate the old libbpf attach (with out links) as well as the new libbpf attach style (with links).
Removed temporary ebpf_link_mark_as_legacy_mode API.

Testing

CI/CD

Documentation

Updated API doxygen.

Installation

No.

This pull request refactors the eBPF user-mode API to simplify program attachment workflows and management of link lifetimes. The main change is to make the output link pointer optional in program attach APIs, and to internalize legacy mode handling so callers no longer need to manually mark links as legacy. Several APIs and internal functions are updated to reflect these changes, and related cleanup is performed in both the API and sample code.

API and Function Signature Changes

• Made the output link pointer (struct bpf_link** link) and link file descriptor (fd_t* link) parameters optional in all eBPF program attach APIs (ebpf_program_attach, ebpf_program_attach_by_fd, ebpf_program_attach_by_fds), by changing them to use _Outptr_opt_ and _Out_opt_ annotations. This allows callers to pass nullptr if they do not need the link object or fd. ([[1]](https://github.com/microsoft/ebpf-for-windows/pull/4690/files#diff-8b744ef020b2dae7afefac77b8d1d9664fa3d249c683b307cd393362da9f5e8bL446-R447), [[2]](https://github.com/microsoft/ebpf-for-windows/pull/4690/files#diff-8b744ef020b2dae7afefac77b8d1d9664fa3d249c683b307cd393362da9f5e8bL470-R472), [[3]](https://github.com/microsoft/ebpf-for-windows/pull/4690/files#diff-8b744ef020b2dae7afefac77b8d1d9664fa3d249c683b307cd393362da9f5e8bL486-R488))
• Updated internal implementations in ebpf_api.cpp to handle optional link outputs, including allocation and assignment logic, and to avoid assertions on non-null output pointers. ([[1]](https://github.com/microsoft/ebpf-for-windows/pull/4690/files#diff-5838f7744d41bcd6c7dc0e9b88628baa36b2a2645824c76aa15f01955ac9cefeL1610-R1625), [[2]](https://github.com/microsoft/ebpf-for-windows/pull/4690/files#diff-5838f7744d41bcd6c7dc0e9b88628baa36b2a2645824c76aa15f01955ac9cefeL1653-R1707), [[3]](https://github.com/microsoft/ebpf-for-windows/pull/4690/files#diff-5838f7744d41bcd6c7dc0e9b88628baa36b2a2645824c76aa15f01955ac9cefeL1683-L1686), [[4]](https://github.com/microsoft/ebpf-for-windows/pull/4690/files#diff-5838f7744d41bcd6c7dc0e9b88628baa36b2a2645824c76aa15f01955ac9cefeL1710-R1765))

Link Legacy Mode Handling

• Removed the public API ebpf_link_mark_as_legacy_mode and replaced it with an internal function _ebpf_link_mark_as_legacy_mode. Legacy mode is now set automatically if the caller does not request a link or fd, so callers do not need to manage this explicitly. ([[1]](https://github.com/microsoft/ebpf-for-windows/pull/4690/files#diff-2f82d1ff51a61fb435467ba5290591820cb88e359100a25e9b9a8e7913c6577cL132), [[2]](https://github.com/microsoft/ebpf-for-windows/pull/4690/files#diff-8b744ef020b2dae7afefac77b8d1d9664fa3d249c683b307cd393362da9f5e8bL909-L920), [[3]](https://github.com/microsoft/ebpf-for-windows/pull/4690/files#diff-5838f7744d41bcd6c7dc0e9b88628baa36b2a2645824c76aa15f01955ac9cefeL5226-L5235))
• Updated program attach logic to internally mark links as legacy when neither link nor fd is requested, and to clean up handles appropriately. ([libs/api/ebpf_api.cppL1629-R1663](https://github.com/microsoft/ebpf-for-windows/pull/4690/files#diff-5838f7744d41bcd6c7dc0e9b88628baa36b2a2645824c76aa15f01955ac9cefeL1629-R1663))

Cleanup and Refactoring in Sample and Helper Code

• Removed manual legacy mode marking and link cleanup from sample code and helper functions, including bpf_prog_attach and __bpf_set_link_xdp_fd_replace in libbpf_program.cpp, and from Netsh sample code in programs.cpp. This simplifies usage and reduces risk of resource leaks. ([[1]](https://github.com/microsoft/ebpf-for-windows/pull/4690/files#diff-780511a42f3cac926001942e228bf075fec98dafebcbef6f1c6f5ce257068839L260-R264), [[2]](https://github.com/microsoft/ebpf-for-windows/pull/4690/files#diff-780511a42f3cac926001942e228bf075fec98dafebcbef6f1c6f5ce257068839L274-L281), [[3]](https://github.com/microsoft/ebpf-for-windows/pull/4690/files#diff-780511a42f3cac926001942e228bf075fec98dafebcbef6f1c6f5ce257068839L641-R632), [[4]](https://github.com/microsoft/ebpf-for-windows/pull/4690/files#diff-9ebbb96ca59e504fcf42e194b161976b696a71ad048cbe73e587a78e084c7a90L266-L283), [[5]](https://github.com/microsoft/ebpf-for-windows/pull/4690/files#diff-9ebbb96ca59e504fcf42e194b161976b696a71ad048cbe73e587a78e084c7a90L478-R457))
• Removed the _link_deleter struct from Netsh sample code, as manual link cleanup is no longer needed. ([libs/ebpfnetsh/programs.cppL112-L122](https://github.com/microsoft/ebpf-for-windows/pull/4690/files#diff-9ebbb96ca59e504fcf42e194b161976b696a71ad048cbe73e587a78e084c7a90L112-L122))

Minor Code Formatting

• Improved code formatting for readability in several places, such as buffer allocation and struct initialization. ([[1]](https://github.com/microsoft/ebpf-for-windows/pull/4690/files#diff-5838f7744d41bcd6c7dc0e9b88628baa36b2a2645824c76aa15f01955ac9cefeL1486-R1492), [[2]](https://github.com/microsoft/ebpf-for-windows/pull/4690/files#diff-5838f7744d41bcd6c7dc0e9b88628baa36b2a2645824c76aa15f01955ac9cefeL2762-R2800))

---

These changes streamline eBPF program attachment by making link management more automatic and reducing the burden on callers, while improving code clarity and safety.

[dthaler]

Suggested change

If you update this PR for some other reason. No need to update just for this though.

[saxena-anurag]

though it is existing code, does this function need to take both handle and fd as out params? the caller can create an fd from the handle itself?

[saxena-anurag]

nit: new_link will not be nullptr here, as there is already a check at line 1750.