aix: clean up module by dybucc · Pull Request #5259 · rust-lang/libc

dybucc · 2026-07-07T11:01:15Z

Description

this pr is concerned with the aix module. each patch addresses either one of (1) adding new bindings, (2) moving the powerpc64 module bindings into the top-level aix module, or (3) more gracefully handling lfs-compliant types and routines. other minor clean ups are also included.

i will not comment on new bindings. these were only added as a consequence of my checking through the header files with which the below items are concerned with.
the merging of the aix/powerpc64 module into the aix module has been made due to this being the only supported rust target using aix. there were already aix module definitions for sum types whose fields were conditionally compiled and assumed to be of one type or another depending on machine word size. in those cases, existing definitions preferred 64-bit-relative code paths. this transition has also required reworking some type definitions. they either (1) used currently non-standard naming for fields declared through anonymous records/unions, (2) were exposing kernel types when these should be provided as opaque types, or (3) were exposing incomplete types that actually had full definitions in upstream header files. lastly, there were some types that simply did not exist at all. i assume that ows to aix version differences between the time when the bindings were initially provided/modified and the current declarations.
lfs handling required some careful consideration. in 64-bit aix targets, most "64"-suffixed types have equivalent definitions with the unsuffixed types. the only exception to this was found in two record types; statvfs and statfs. each of these contains one field of type fsid_t. this type is unconditionally declared as having an effective size of 8 bytes and a 4-byte alignment requirement. the fsid64_t type has an effective size of 16 bytes and an 8-byte alignment requirement. the latter is used in the statvfs64 and statfs64 types. the routines making use of these can neither be assumed to have equivalent signatures, so the suffixed variants have been gated under the aix_large_file_api cfg. the gnu_file_offset_bits64 cfg could have probably been reused, but i have decided against that to favor tidiness.

Sources

files sys/types.h, sys/inttypes.h, sys/lock_def.h, sys/ptrace.h, sys/stat.h, sys/statfs.h, sys/statvfs.h under /usr/include on any aix 7.3 machine.

links cannot be provided. sources are not public.

Checklist

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

tgross35

@xingxue-ibm would you be able to take a look?

View changes since this review

tgross35 · 2026-07-09T01:40:18Z

+    pub fn ptrace(request: c_int, id: c_int, address: *mut c_int, data: c_int, buffer: *mut c_int);
+    pub fn ptracex(request: c_int, id: c_int, address: c_longlong, data: c_int, buffer: *mut c_int);


"aix: add new ptrace routines": is there a usecase for these?

none that i know of. i've removed them now.

I'm sure somebody wouldn't mind having them, but that can come separately from any kind of cleanup

tgross35 · 2026-07-09T01:41:00Z

+    let aix_large_file_api = env_flag("CARGO_CFG_LIBC_UNSTABLE_LARGE_FILE_API");
+    if aix_large_file_api {
+        set_cfg("aix_large_file_api");
+    }


"aix: add cfg for certain lfs bindings": This is effectively deleting API that people may be using?

that's right.

Please always call out breakage in commit messages, I almost overlooked this aspect.

What was the thought process here? Outright removing these is likely to break a lot of people.

done. noted.

what do you mean by the thought process? much like other cfgs, i added them to fit an upstream feature test macro that is checked before making the type definitions available. i didn't mention it in the commit because i thought not marking the pr as stable-nominated would do.

We won't have any use for this config in 1.0, we can just delete the *64 versions on platforms where they're identical.

Most PRs should be intended for backport - I hadn't realized you weren't on the same page. I'll post more about this at #5170 very soon.

i think that much i already understand (meaning the 64-bit types, not the backporting stuff.) the thing with the types i specifically gated behind the cfg is that they are not equivalent to the unsuffixed types unless the upstream macro is defined. in fact, there's a bunch more 64-suffixed types that i did not annotate but rather deprecated because they are, indeed, equivalent if we assume the macro is defined. only those that i annotated in that commit are not; namely, statfs, statvfs, and routines that use them. the ones that i deprecated have now been annotated with the comment you mention in #4805.

i can't provide links because the sources are not public. there's neither any page in the ibm docs that comments on it.

Are our current definitions (before this PR) correct if we assume the macro is defined?

tgross35 · 2026-07-09T01:41:46Z

+    pub struct _simple_lock {
+        pub _slock: simple_lock_data,
+        pub _slockp: *mut lock_data_instrumented,
+    }
+
+    pub struct _complex_lock {
+        pub _clock: complex_lock_data,
+        pub clockp: *mut lock_data_instrumented,
+    }
+
+    pub struct _drw_lock {
+        pub _drwlock: complex_lock_status,
+        pub _drwlockp: *mut lock_data_instrumented,
+    }
+
+    pub struct complex_lock_data {
+        pub status: complex_lock_status,
+        pub flags: c_short,
+        pub recursion_depth: c_short,
+        pub reserved: c_uint,
+    }
+
+    pub struct drw_lock_data {
+        pub status: complex_lock_status,
+    }


"aix: add new auxiliary lock records": is there a usecase for these?

yup, they're used in the lock_data_instrumented type that was previously in the aix/powerpc64 module. we were exposing it as an opaque type even though upstream has a full definition. i've merged those commits to make it more cohesive.

not sure if that counts as an api addition.

As far as I can tell, these are kernel-internal structures so we're probably safer leaving them opaque. That tends to be the rule of thumb for anything not publicly documented, and I can't find any manpages on these.

except they're not. i explicitly skipped those and, in fact, added a deprecation notice to a type that is only exposed when programming against the kernel ¹.

Footnotes

https://github.com/rust-lang/libc/pull/5259/changes#diff-cdca763d7494a8b247c48e3d317bd4dfbd7c2792f4363fa5070805958650b44aR993-R1017 ↩

I still had no luck couldn't find something in their manpages, could you share a link?

sources aren't public and i'm not sure i can legally disclose the header file contents. still, i can say it's quite odd. the header file in which those types are declared in is not gated behind the kernel macros i've seen aix use in other header files. and yet here ¹, there's mention of one of the routines in the header file being a so called kernel service, when that same routine is not gated behind kernel macros in said header file.

Footnotes

https://www.ibm.com/docs/en/aix/7.3.0?topic=s-simple-lock-init-kernel-service ↩

Right, I'm not asking to look at the headers (I do have access). This isn't about what's gated behind macros, headers invariably have a ton of internal and public API mixed together because that's just how C is. Having documentation in the manpages is kind of supposed to be the way to tell whether something is user-facing or not.

That's not super reliable on all platforms because some are just poorly documented, but we can usually rely on it for AIX (at this site) and glibc at least.

Anyway I'm fine to take the structural change here, but the fields and new structures should be made private.

tgross35 · 2026-07-09T02:41:10Z

"aix: move and fix powerpc64 definitions into aix": I have mixed feelings on this change. On one hand there are likely no other platforms we will ever need to support with AIX, according to https://en.wikipedia.org/wiki/IBM_AIX. On the other hand, having types like mcontext_t in a non-arch-specific module feels very wrong.

I think I'd have a mild preference of moving this to src/new and matching system headers, if moved at all, that's one fewer history jump in the blame once everything makes it to new eventually anyway. But I'll leave it up to the target maintainers.

rustbot · 2026-07-09T02:55:25Z

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

dybucc · 2026-07-09T09:34:47Z

i'll change the pr status once the target maintainer answers.

simplify crate-relative item paths to use self-module-relative paths. replace uses of deprecated fixed-width c integer types with rust integer types.

add new cfg to expose lfs-compliant definitions in aix. aix has virtually equivalent definitions for "64"-suffixed and unsuffixed types under 64-bit machine word targets. we are currently targetting only powerpc64. the exception to this include the records and routines that do need a cfg because their effective size and alignment (in the case of records) are different among suffixed and unsuffixed variants. c.f. sys/stat.h, sys/statfs.h and sys/statvfs.h under /usr/include on any aix 7.3 machine. BREAKING CHANGE: gated types are no longer available unless the cfg is set.

add comments for deprecation once stage 3 of the 64-bit plan is reached [^1]. [^1]: rust-lang#4805

move all type definitions and routine bindings into the aix top-level module. the only supported target using aix is powerpc64. this has been the case for some time. multiple existing definitions whose upstream header conditionally uses different types for 32-bit and 64-bit machine word sizes were already preferring the latter. remove the aix/powerpc64 module. all bindings now live in the top-level aix module. fix some definitions. there were quite a few types that were either declared with the wrong identifiers, were exposed as opaque types when they're not upstream, or were otherwise only exposed in kernel mode. existing sum types with conditionally compiled fields that rely on this latter fact assume we are not compiling for that type of processes. this assumption has transitively applied to the types brought over from the powerpc64 submodule.

rustbot · 2026-07-09T15:46:40Z

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.

xingxue-ibm · 2026-07-09T20:52:32Z

Thanks for the effort, @dybucc! Your contribution is greatly appreciated. As discussed with the Rust product team, we believe it is not entirely out of the question that we may add AIX 32-bit support in the future. As such, we kindly suggest holding off on the cleanup for now.

tgross35 · 2026-07-10T01:45:20Z

+        #[cfg(debug_assertions)]
+        pub lock_lr: c_int,
+        #[cfg(debug_assertions)]
+        pub unlock_lr: c_int,
+        #[cfg(debug_assertions)]
+        pub lock_caller: tid_t,
+        #[cfg(debug_assertions)]
+        pub unlock_caller: tid_t,
+        #[cfg(debug_assertions)]
+        pub lock_cpuid: c_int,
+        #[cfg(debug_assertions)]
+        pub dbg_zero: c_int,
+        #[cfg(debug_assertions)]
+        pub unlock_cpuid: c_int,
+        #[cfg(debug_assertions)]
+        pub dbg_flags: c_int,


This appears to give the struct a different size based on how you build libc

View changes since the review

rustbot added the S-waiting-on-review label Jul 7, 2026

dybucc force-pushed the aix-cleanup branch from 9f387ae to 5536ea8 Compare July 7, 2026 13:50

tgross35 requested changes Jul 9, 2026

View reviewed changes

rustbot added S-waiting-on-author and removed S-waiting-on-review labels Jul 9, 2026

dybucc force-pushed the aix-cleanup branch from 5536ea8 to 395b736 Compare July 9, 2026 09:33

This comment has been minimized.

Sign in to view

tgross35 added the S-waiting-on-maintainer label Jul 9, 2026

dybucc force-pushed the aix-cleanup branch from 395b736 to b49621f Compare July 9, 2026 11:03

dybucc added 5 commits July 9, 2026 17:45

aix: annotate lfs types as slated for deprecation

ec50d7c

aix: clean up item paths

d612fad

simplify crate-relative item paths to use self-module-relative paths. replace uses of deprecated fixed-width c integer types with rust integer types.

aix: annotate most lfs routines for deprecation

825c193

add comments for deprecation once stage 3 of the 64-bit plan is reached [^1]. [^1]: rust-lang#4805

dybucc force-pushed the aix-cleanup branch from b49621f to faccc1c Compare July 9, 2026 15:46

tgross35 reviewed Jul 10, 2026

View reviewed changes

		pub fn ptrace(request: c_int, id: c_int, address: mut c_int, data: c_int, buffer: mut c_int);
		pub fn ptracex(request: c_int, id: c_int, address: c_longlong, data: c_int, buffer: *mut c_int);

Uh oh!

Conversation

dybucc commented Jul 7, 2026

Description

Sources

Checklist

Uh oh!

tgross35 left a comment • edited by rustbot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Footnotes

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Footnotes

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rustbot commented Jul 9, 2026

Uh oh!

This comment has been minimized.

dybucc commented Jul 9, 2026

Uh oh!

rustbot commented Jul 9, 2026

Uh oh!

xingxue-ibm commented Jul 9, 2026

Uh oh!

tgross35 Jul 10, 2026 • edited by rustbot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

tgross35 left a comment •

edited by rustbot

Loading

tgross35 Jul 10, 2026 •

edited by rustbot

Loading