Skip to content

Implement statx syscall for extended file metadata #613

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Draft
wdcui wants to merge 2 commits into
base: main
Choose a base branch
from
Draft

Implement statx syscall for extended file metadata #613

wdcui wants to merge 2 commits into from
+834 −2

Conversation

@wdcui
Copy link
Member

@wdcui wdcui commented Feb 1, 2026

Summary

Add support for the Linux statx(2) syscall which provides extended file metadata retrieval capabilities beyond the traditional stat family of syscalls.

Syscall Details

int statx(int dirfd, const char *pathname, int flags, unsigned int mask, struct statx *statxbuf);

Changes

File Changes
litebox_common_linux/src/lib.rs Add Statx, StatxTimestamp, StatxFlags, StatxMask types; add Statx variant to SyscallRequest; add syscall parsing
litebox_shim_linux/src/lib.rs Add dispatch case for SyscallRequest::Statx
litebox_shim_linux/src/syscalls/file.rs Implement sys_statx() method with flag/mask validation, path resolution
litebox_shim_linux/src/syscalls/tests.rs Add 7 unit tests

Supported Features

  • ✅ Basic file metadata (type, mode, uid, gid, ino, size)
  • ✅ AT_EMPTY_PATH flag for operating on file descriptors directly
  • ✅ AT_SYMLINK_NOFOLLOW flag for not following symlinks
  • ✅ AT_STATX_FORCE_SYNC / AT_STATX_DONT_SYNC flag validation
  • ✅ Directory metadata
  • ✅ Device major/minor number decoding

Known Limitations

  • Timestamps (atime, mtime, ctime, btime) return 0 (not tracked in litebox)
  • stx_blocks returns 0 (not tracked)
  • stx_mnt_id returns 0 (mount ID not tracked)
  • Direct I/O alignment fields return 0 (not supported)

Error Handling

Error Condition
EINVAL Conflicting flags (FORCE_SYNC + DONT_SYNC)
EINVAL Reserved bits set in mask
ENOENT File does not exist
EBADF Invalid file descriptor with AT_EMPTY_PATH
EFAULT Invalid pointer

Test Coverage

  • test_statx_basic - Basic statx on a regular file
  • test_statx_empty_path - AT_EMPTY_PATH with fd
  • test_statx_invalid_flags - EINVAL for conflicting flags
  • test_statx_invalid_mask - EINVAL for reserved mask bits
  • test_statx_enoent - ENOENT for non-existent file
  • test_statx_ebadf - EBADF for invalid dirfd
  • test_statx_directory - Directory metadata

Test plan

  • All 7 statx unit tests pass
  • All 181 workspace tests pass
  • cargo clippy --all-targets --all-features -- -D warnings clean
  • cargo fmt --all -- --check clean
  • CI passes

🤖 Generated with Claude Code

wdcui and others added 2 commits February 1, 2026 21:26
@wdcui @claude
Implement statx syscall for extended file metadata
0482f58 
Add support for the Linux statx(2) syscall which provides extended file
metadata retrieval capabilities beyond the traditional stat family.

## Changes

### litebox_common_linux/src/lib.rs
- Add `StatxFlags` bitflags (AT_EMPTY_PATH, AT_SYMLINK_NOFOLLOW, etc.)
- Add `StatxMask` bitflags (STATX_TYPE, STATX_MODE, STATX_BASIC_STATS, etc.)
- Add `StatxTimestamp` struct (16 bytes, matches Linux ABI)
- Add `Statx` struct (256 bytes, architecture-independent)
- Add `From<FileStatus> for Statx` conversion
- Add `Statx` variant to `SyscallRequest` enum
- Add syscall parsing for `Sysno::statx`

### litebox_shim_linux/src/lib.rs
- Add dispatch case for `SyscallRequest::Statx`

### litebox_shim_linux/src/syscalls/file.rs
- Implement `sys_statx()` method with:
  - Flag validation (FORCE_SYNC/DONT_SYNC mutually exclusive)
  - Mask validation (reject STATX_RESERVED)
  - AT_EMPTY_PATH support
  - AT_SYMLINK_NOFOLLOW support
  - Path resolution via FsPath
- Add `filestat_to_statx()` helper for FileStat to Statx conversion

### litebox_shim_linux/src/syscalls/tests.rs
- Add 7 unit tests for statx functionality

## Supported Features
- Basic file metadata (type, mode, uid, gid, ino, size)
- AT_EMPTY_PATH flag for operating on file descriptors directly
- AT_SYMLINK_NOFOLLOW flag for not following symlinks
- Directory metadata

## Known Limitations
- Timestamps (atime, mtime, ctime, btime) return 0 (not tracked)
- stx_blocks returns 0 (not tracked)
- stx_mnt_id returns 0 (mount ID not tracked)
- Direct I/O alignment fields return 0 (not supported)

Co-Authored-By: Claude Opus 4.5 <[email protected]>
@wdcui @claude
Address review feedback for statx implementation
65f6124 
## ABI Fixes (Critical)
- Fix Statx struct to include all Linux fields:
  - stx_subvol (subvolume identifier)
  - stx_atomic_write_unit_min/max (atomic write limits)
  - stx_atomic_write_segments_max (atomic write segments)
  - stx_dio_read_offset_align (direct I/O read alignment)
  - stx_atomic_write_unit_max_opt (optimized atomic write max)
  - __spare2 padding
  - Reduced __spare3 from 12 to 8 u64s
- Add compile-time assertion for struct size (256 bytes)
- Fix device number encoding to use Linux 20-bit minor numbers
  (major = dev >> 20, minor = dev & 0xfffff)

## Additional Tests
- test_statx_empty_path_without_flag: empty path without AT_EMPTY_PATH
- test_statx_symlink_nofollow_flag: AT_SYMLINK_NOFOLLOW flag acceptance
- test_statx_invalid_negative_dirfd: invalid negative dirfd (not AT_FDCWD)
- test_statx_eventfd: statx on eventfd descriptor
- test_statx_pipe: statx on pipe descriptor

Total: 12 statx tests (was 7)

Co-Authored-By: Claude Opus 4.5 <[email protected]>
@github-actions
Copy link

github-actions bot commented Feb 1, 2026

🤖 SemverChecks 🤖 ⚠️ Potential breaking API changes detected ⚠️

Click for details 
--- failure enum_no_repr_variant_discriminant_changed: enum variant had its discriminant change value ---

Description:
The enum's variant had its discriminant value change. This breaks downstream code that used its value via a numeric cast like `as isize`.
        ref: https://doc.rust-lang.org/reference/items/enumerations.html#assigning-discriminant-values
       impl: https://github.com/obi1kenobi/cargo-semver-checks/tree/v0.46.0/src/lints/enum_no_repr_variant_discriminant_changed.ron

Failed in:
  variant SyscallRequest::Eventfd2 58 -> 59 in /home/runner/work/litebox/litebox/litebox_common_linux/src/lib.rs:2433
  variant SyscallRequest::Pipe2 59 -> 60 in /home/runner/work/litebox/litebox/litebox_common_linux/src/lib.rs:2437
  variant SyscallRequest::Clone 60 -> 61 in /home/runner/work/litebox/litebox/litebox_common_linux/src/lib.rs:2441
  variant SyscallRequest::Clone3 61 -> 62 in /home/runner/work/litebox/litebox/litebox_common_linux/src/lib.rs:2444
  variant SyscallRequest::SetThreadArea 62 -> 63 in /home/runner/work/litebox/litebox/litebox_common_linux/src/lib.rs:2449
  variant SyscallRequest::ClockGettime 63 -> 64 in /home/runner/work/litebox/litebox/litebox_common_linux/src/lib.rs:2452
  variant SyscallRequest::ClockGetres 64 -> 65 in /home/runner/work/litebox/litebox/litebox_common_linux/src/lib.rs:2456
  variant SyscallRequest::ClockNanosleep 65 -> 66 in /home/runner/work/litebox/litebox/litebox_common_linux/src/lib.rs:2460
  variant SyscallRequest::Gettimeofday 66 -> 67 in /home/runner/work/litebox/litebox/litebox_common_linux/src/lib.rs:2466
  variant SyscallRequest::Time 67 -> 68 in /home/runner/work/litebox/litebox/litebox_common_linux/src/lib.rs:2470
  variant SyscallRequest::Getrlimit 68 -> 69 in /home/runner/work/litebox/litebox/litebox_common_linux/src/lib.rs:2473
  variant SyscallRequest::Setrlimit 69 -> 70 in /home/runner/work/litebox/litebox/litebox_common_linux/src/lib.rs:2477
  variant SyscallRequest::Prlimit 70 -> 71 in /home/runner/work/litebox/litebox/litebox_common_linux/src/lib.rs:2481
  variant SyscallRequest::SetTidAddress 71 -> 72 in /home/runner/work/litebox/litebox/litebox_common_linux/src/lib.rs:2492
  variant SyscallRequest::Gettid 72 -> 73 in /home/runner/work/litebox/litebox/litebox_common_linux/src/lib.rs:2495
  variant SyscallRequest::SetRobustList 73 -> 74 in /home/runner/work/litebox/litebox/litebox_common_linux/src/lib.rs:2496
  variant SyscallRequest::GetRobustList 74 -> 75 in /home/runner/work/litebox/litebox/litebox_common_linux/src/lib.rs:2499
  variant SyscallRequest::GetRandom 75 -> 76 in /home/runner/work/litebox/litebox/litebox_common_linux/src/lib.rs:2504
  variant SyscallRequest::Getpid 76 -> 77 in /home/runner/work/litebox/litebox/litebox_common_linux/src/lib.rs:2509
  variant SyscallRequest::Getppid 77 -> 78 in /home/runner/work/litebox/litebox/litebox_common_linux/src/lib.rs:2510
  variant SyscallRequest::Getuid 78 -> 79 in /home/runner/work/litebox/litebox/litebox_common_linux/src/lib.rs:2511
  variant SyscallRequest::Geteuid 79 -> 80 in /home/runner/work/litebox/litebox/litebox_common_linux/src/lib.rs:2512
  variant SyscallRequest::Getgid 80 -> 81 in /home/runner/work/litebox/litebox/litebox_common_linux/src/lib.rs:2513
  variant SyscallRequest::Getegid 81 -> 82 in /home/runner/work/litebox/litebox/litebox_common_linux/src/lib.rs:2514
  variant SyscallRequest::Sysinfo 82 -> 83 in /home/runner/work/litebox/litebox/litebox_common_linux/src/lib.rs:2515
  variant SyscallRequest::CapGet 83 -> 84 in /home/runner/work/litebox/litebox/litebox_common_linux/src/lib.rs:2518
  variant SyscallRequest::GetDirent64 84 -> 85 in /home/runner/work/litebox/litebox/litebox_common_linux/src/lib.rs:2522
  variant SyscallRequest::SchedGetAffinity 85 -> 86 in /home/runner/work/litebox/litebox/litebox_common_linux/src/lib.rs:2527
  variant SyscallRequest::SchedYield 86 -> 87 in /home/runner/work/litebox/litebox/litebox_common_linux/src/lib.rs:2532
  variant SyscallRequest::Futex 87 -> 88 in /home/runner/work/litebox/litebox/litebox_common_linux/src/lib.rs:2533
  variant SyscallRequest::Execve 88 -> 89 in /home/runner/work/litebox/litebox/litebox_common_linux/src/lib.rs:2536
  variant SyscallRequest::Umask 89 -> 90 in /home/runner/work/litebox/litebox/litebox_common_linux/src/lib.rs:2541
  variant SyscallRequest::Prctl 90 -> 91 in /home/runner/work/litebox/litebox/litebox_common_linux/src/lib.rs:2544
  variant SyscallRequest::Alarm 91 -> 92 in /home/runner/work/litebox/litebox/litebox_common_linux/src/lib.rs:2547
  variant SyscallRequest::SetITimer 92 -> 93 in /home/runner/work/litebox/litebox/litebox_common_linux/src/lib.rs:2550

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@wdcui