libusb_get_port_numbers returns nothing on some macOS versions

[eswierk]

The name of the IORegistry port property is not consistent across macOS versions: it's port on some, usb-port-number on others. (Run ioreg -c AppleUSB30HubPort or ioreg -c AppleUSB20HubPort to show the properties on your Mac.)

get_device_port in os/darwin_usb.c should pass kUSBHostPortPropertyPortNumber rather than "port" to get_ioregistry_value_data. This makes libusb_get_port_numbers return port numbers on all recent versions of macOS.

[mvp]

@eswierk, unfortunately this is not very good approach and arguably is macOS 26 bug.
Scenario: I have an executable (e.g. uhubctl) that links to libusb and built using MacOSX15.5 sdk or earlier, and suppose I even patched libusb to use macro kUSBHostPortPropertyPortNumber as you suggest.

However, such executable will not work correctly in macOS 26 because this macro would have "port" linked into it, but macOS 26 would require "usb-port-number" to work correctly.

Better way to fix this is to use function get_running_version() defined in os/darwin_usb.c and pass port or usb-port-number depending on currently running macOS version. Or, better yet, have Apple rollback macOS 26 USB stack to use "port" like it always did before it goes out of beta.

[eswierk]

Good point. My bias is showing — on Linux, there's no such thing as building against one version of the OS and running on a different one, unless you're statically linking the universe.

[seanm]

Apple usually takes binary-compatibility bugs pretty seriously, at least they used to. I would definitely file a bug. Could you post the FB number here once you do? And even the text of your bug report if you don't mind...

[mvp]

@eswierk, unless I am mistaken you are current Apple employee? So you are most equipped to file this or solve this issue on macOS side?

[mvp]

Filed to Apple feedback https://feedbackassistant.apple.com/feedback/18170043. Full text is below:

macOS 26 breaks backwards USB compatibility with libusb

Please provide a descriptive title for your feedback:
macOS 26 breaks backwards USB compatibility with libusb

Which area are you seeing an issue with?
USB/Thunderbolt

What type of issue are you reporting?
Incorrect/Unexpected Behavior

Description
Please describe the issue and what steps we can take to reproduce it:

On macOS 15.5 and any previous versions, IORegistry IOUSB plane port property was always "port". However, on macOS 26 Tahoe "port" does not work, but "usb-port-number" does.

I am a developer for open source software uhubctl https://github.com/mvp/uhubctl.
This utility depends on open source library libusb which among other platforms supports MacOS - all versions from 10.x to 15.5.

macOS Tahoe 26 beta testers reported that my software does not work on macOS 26
mvp/uhubctl#623.

Upon closer inspection it turned out that in macOS 26 libusb is not able to read USB port properties #1661.

Steps to reproduce:

Run command line ioreg -c AppleUSB20HubPort -l.

Expected result:

You should see that port property have name "port" e.g.
"port" = <01000000>
"port" = <02000000>
This is what observed on macOS 15.5 and earlier.

Actual result:

On macOS 26, you will see this instead:
"usb-port-number" = <01000000>...
Also, any utility that depends on libusb will not work correctly or at all.

Solution that was tested to work on macOS 26 was to patch libusb to refer to port property as "usb-port-number" instead of "port" https://github.com/libusb/libusb/blob/3dbfa16/libusb/os/darwin_usb.c#L1263.

libusb developers consider this breaking backwards binary compatibility by macOS #1661 (comment).

Please revert back to using "port" property before macOS 26 goes out of beta, so this issue does any software dependent on libusb.

[seanm]

I submitted similar as FB18234941. I encourage others to do so too; duplicate bug reports increases priority.

[parisbutterfield]

Beta 4 25A5316i of macOS 26 is still using usb-port-number. I opened a bug with Apple a few weeks ago, but haven't heard anything. How can we amplify this issue?

"usb-port-number" = <02000000>
    | |   | |       "locationID" = 35651584
    | |   | |       "kUSBWakePortCurrentLimit" = 3000
    | |   | |       "port-status" = 5
    | |   | |       "UsbCPortNumber" = 3
    | |   | |       "usb-c-port-number" = <03000000>

[seanm]

I opened a bug with Apple a few weeks ago, but haven't heard anything.

Which is typical. Apple's bug reporting system is widely known as a black hole: information enters, but never exits. :(

How can we amplify this issue?

More reports increases priority. Otherwise pray?

[seanm]

So macOS 26 is now just about released... anyone check if this was fixed?

Of course my bug report had no response whatsoever, as usual from Apple.

[parisbutterfield]

I didn't get a response to my ticket either. The RC build 26.0 (25A353) is showing

 % ioreg -c AppleUSB20HubPort -l | grep "\"port-number"\"
    | |   |         |   "port-number" = <01000000>
    | |   | |   "port-number" = <01000000>
    | |   | |   "port-number" = <01000000>
    | |   | |   "port-number" = <02000000>
    | |   | |   "port-number" = <02000000>
    | |   | |   "port-number" = <03000000>
    | |   | |   "port-number" = <03000000>
    | |   | |   "port-number" = <01000000>
    | |   | |   "port-number" = <01000000>
    | |   | |   "port-number" = <01000000>

and ioreg -c AppleUSB20HubPort -l | grep "\"port"\" returns no results.

[mvp]

Interesting. So they did change it from "usb-port-number" in first rc to "port-number" in last one. This suggests that reverting back to "port" is highly unlikely 😢

[paulzaptec]

Unfortunately this bug is still present in the release version of macOS 26.0