Skip to content

docs: clarify byte units for size-based ulimits (memlock)#7115

Open
locker95 wants to merge 1 commit into
docker:masterfrom
locker95:docs/ulimit-memlock-units-5799
Open

docs: clarify byte units for size-based ulimits (memlock)#7115
locker95 wants to merge 1 commit into
docker:masterfrom
locker95:docs/ulimit-memlock-units-5799

Conversation

@locker95

Copy link
Copy Markdown

- What I did

Documented the units for size-based --ulimit values.

The values of --ulimit options are passed to the setrlimit(2) syscall as-is, so size-based limits such as memlock, data, and fsize are expressed in bytes. The ulimit shell builtin, however, reports several of these limits in kilobytes, so --ulimit memlock=4096 produces a limit that ulimit -l reports as 4. That's counter-intuitive for users expecting the same units as the shell, and it wasn't documented. Values must also be plain integers; unit suffixes such as k, m, or g aren't supported.

This PR only clarifies the documentation and doesn't change any behavior. Accepting human-friendly suffixes (for example --ulimit memlock=64m) could be a follow-up enhancement if maintainers think it's worthwhile, but that changes option parsing and deserves its own discussion.

Fixes #5799

- How I did it

  • Extended the --ulimit section in docs/reference/commandline/container_run.md: documented that size-based limits are in bytes (following setrlimit(2) semantics) and that values must be plain integers without unit suffixes, and added a note with a memlock example showing the byte value (67108864 = 64 MiB) next to the corresponding ulimit -l output (65536, in kilobytes).
  • Expanded the terse --ulimit entry in man/docker-run.1.md with the same information.

- How to verify it

Documentation-only change; review the rendered Markdown. The documented behavior can be verified with:

$ docker run --ulimit memlock=67108864:67108864 --rm debian sh -c "ulimit -l"
65536

- Human readable description for the release notes

The values for size-based ulimits, such as memlock, data, and fsize,
are passed to the setrlimit(2) syscall as-is, and are therefore
expressed in bytes. This differs from the ulimit shell builtin, which
reports several of these limits in kilobytes, which has proven to be
a source of confusion (--ulimit memlock=4096 results in a 4 KiB limit,
reported by "ulimit -l" as "4").

Document the units explicitly, mention that values must be plain
integers without unit suffixes, and add a memlock example showing
the byte value alongside the corresponding "ulimit -l" output.

Signed-off-by: Dean Chen <862469039@qq.com>
@locker95
locker95 requested review from a team and thaJeztah as code owners July 22, 2026 04:37
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Units for --ulimit memlock is counter intuitive

1 participant