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

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>

Author: locker95

docs/reference/commandline/container_run.md

@@ -1370,7 +1370,21 @@ $ docker run --ulimit nofile=1024:1024 --rm debian sh -c "ulimit -n"
 | `stack`      | Maximum stack size (`RLIMIT_STACK`)                       |
 
 Docker sends the values to the appropriate OS `syscall` and doesn't perform any byte conversion.
-Take this into account when setting the values.
+For limits that describe a size, such as `memlock`, `data`, and `fsize`, values
+are in bytes, following the semantics of the Linux `setrlimit(2)` syscall.
+Values must be plain integers, and don't support unit suffixes such as `k`,
+`m`, or `g`.
+
+> [!NOTE]
+> The `ulimit` shell builtin reports some of these limits in different units.
+> For example, `ulimit -l` reports the `memlock` limit in kilobytes, so a limit
+> of 64 MiB set with `--ulimit memlock=67108864:67108864` is reported as
+> `65536`:
+>
+> ```console
+> $ docker run --ulimit memlock=67108864:67108864 --rm debian sh -c "ulimit -l"
+> 65536
+> ```
 
 #### For `nproc` usage
 

man/docker-run.1.md

@@ -740,7 +740,15 @@ any options, the systems uses the following options:
    Without this argument the command will be run as root in the container.
 
 **--ulimit**=[]
-    Ulimit options
+   Ulimit options, in the format `<type>=<soft limit>[:<hard limit>]`, for
+   example `--ulimit nofile=1024:1024`.
+
+   Limits that describe a size, such as `memlock`, `data`, and `fsize`, are
+   specified in bytes, as used by the Linux setrlimit(2) syscall. Values must
+   be plain integers, and don't support unit suffixes such as `k`, `m`, or
+   `g`. Note that the `ulimit` builtin of the shell reports some of these
+   limits in different units, for example, `ulimit -l` reports the `memlock`
+   limit in kilobytes.
 
 **-v**|**--volume**[=*[[HOST-DIR:]CONTAINER-DIR[:OPTIONS]]*]
    Create a bind mount. If you specify, ` -v /HOST-DIR:/CONTAINER-DIR`, Docker